path: root/docs/superpowers/plans/2026-08-03-post-0.1.0-usability.md

# Post-0.1.0 usability backlog

Status: **open, expandable by design.** This document is not a fixed release
plan. It collects items found by actually using qtmaildir after 0.1.0, and it
grows as more turn up. Nothing here is scheduled; picking what ships in a given
release is a separate decision.

Source: usage notes taken while running the app, 2026-08-03.

**Numbers here are this document's own.** The user's own notes were numbered
independently and the two sequences drifted apart once items were split: what
those notes called 12 is item 13 here, and item 14 here (the tag column) was
never in them at all. Items 15 to 17 come from a later pass over the same
notes. Cite these numbers, not the notes', and do not renumber to reconcile.

Numbering is stable. New items append with the next free number and never
renumber, so a note referring to "item 7" keeps meaning the same thing. An item
that is dropped stays in the table marked `dropped` with a one-line reason.

## Theme

0.1.0 was built to a spec written by someone who lives in neomutt. The result
is a keyboard-driven reader with almost no visible affordances. The notes below
are, with few exceptions, one complaint restated in several forms: **the app
does not tell the user what it can do, and it does not remember what the user
told it.** Two clusters follow from that:

- **Persistence.** Splitter position, font size, window geometry, and the
  account selection all reset on restart. Each is small on its own and
  aggravating every single launch.
- **Discoverability.** Shortcuts are the only route to most actions, and there
  is no menu bar, no toolbar, and no way to see the key bindings from inside
  the app.

Both clusters are cheap to fix. Neither was an oversight in design so much as a
consequence of specifying the app as "a GUI counterpart to neomutt" and then
taking that too literally.

## Status table

| # | Item | Cluster | Size | Status |
|---|------|---------|------|--------|
| 1 | Splitter/column widths do not survive restart | persistence | S | **done** |
| 2 | No way to see full message details (From/To/Cc/Subject) | information | M | **done** |
| 3 | Too few clickable affordances, shortcuts are the only route | discoverability | M | **done** |
| 4 | Message-pane font size does not survive restart | persistence | S | **done** |
| 5 | Thread list is cramped, poor readability | presentation | S | open |
| 6 | Opened message stays unread | behavior | S | **done** |
| 7 | HTML view should be default for HTML messages | behavior | XS | **done** (already worked) |
| 8 | No buttons or menu entries for archive, undo, etc | discoverability | M | **done** |
| 9 | No in-app view of configured shortcuts | discoverability | S | **done** |
| 10 | Reaching an account's inbox takes two steps | workflow | S | **postponed** (partly done) |
| 11 | Icon, `.desktop` file, SlackBuild | packaging | M | **done** |
| 13 | No visual feedback that an action stuck | feedback | S | **done** |
| 14 | Tag column unreadable, tags need another home | presentation | M | **done** |
| 15 | Attachments are parsed but unreachable from the UI | information | M | **done** |
| 16 | Delete on an already-deleted thread should undelete | behavior | S | open |
| 17 | No completion for tags in the query bar | workflow | M | **done** |
| 18 | No visual cue that there are unsynced edits | feedback | S | open |
| 19 | No prompt to sync on exit when edits are pending | behavior | S | open |
| 20 | Thread view does not match the user's mental model | presentation | ? | open, unspecified |
| 21 | Default shortcuts are not sensible enough | discoverability | S | open |
| 22 | Translatability audit and i18n wiring | correctness | M | open |
| 23 | No way to save a search query from the UI | workflow | M | open |

Sizes are rough: XS under an hour, S a sitting, M a session.

---

## 1. Splitter and column widths do not survive restart

**Observed:** resizing the thread list pane, or a column inside it, is undone by
the next launch.

**Cause:** `MainWindow::buildUi()` (`src/mainwindow.cpp:195`) builds the
`QSplitter` fresh every launch, sets a stretch factor, and never saves state.
`resize(1200, 800)` at `src/mainwindow.cpp:206` hardcodes window size too. There
is no `QSettings` window-state read or write anywhere in the class.

**Approach:** one `saveState`/`restoreState` pair in
`MainWindow`, driven from a `QSettings` object separate from the hand-written
config file.

- Save on `closeEvent`, restore at the end of `buildUi()`.
- Persist: `QMainWindow::saveGeometry()`, `QMainWindow::saveState()`,
  `QSplitter::saveState()`, `QHeaderView::saveState()` for the thread list.
- Restore must be a no-op when the stored blob is absent or rejected, falling
  back to the current hardcoded defaults. `restoreGeometry()` returns `false`
  in that case; do not assume it succeeded.

**Where the state file goes.** The hand-edited config lives at
`~/.config/qtmaildir/qtmaildir.conf` and is the user's to own. Machine-written
window blobs must not land in it: a base64 `QByteArray` appearing in a file the
user edits by hand is hostile, and rewriting that file on exit risks clobbering
comments and formatting QSettings does not preserve. Use a **separate**
`QSettings` instance for UI state, at
`~/.local/state/qtmaildir/uistate.conf` or the `QStandardPaths` equivalent, and
keep `Config` untouched.

**Confirmed by the user, 2026-08-03.** This decision covers items 1, 4, and 10
as well. Establish it once, in whichever lands first.

**Verification:** manual. Resize both the window and the splitter, restart,
confirm both held. Then delete the state file and confirm the app still starts
with the 1200x800 default rather than a zero-size window.

### Outcome (done)

Built as described. `MainWindow::uiStatePath()` establishes the state file the
plan calls for, so items 4 and 10 inherit it. Two things worth recording:

- **`QStandardPaths::StateLocation` is the wrong enum here.** It appends both
  the organization and the application name, and this app sets both to
  `qtmaildir`, so it yields `~/.local/state/qtmaildir/qtmaildir/`. The path is
  built from `GenericStateLocation` plus an explicit `/qtmaildir`, the same
  shape as `Config::defaultPath()`. A test pins the component count.
- **`restoreUiState()` runs after `buildMenus()`, not at the end of
  `buildUi()`** as the plan proposed. `QMainWindow::restoreState()` matches
  toolbars by object name, so a toolbar that does not exist yet has its
  position silently dropped.

Every restore is guarded on a non-empty blob, so absent state leaves the
`buildUi()` defaults rather than producing a zero-size window.

## 2. No way to see full message details

**Observed:** From, To, Cc, Subject and the rest are not visible for the
selected message.

**Cause:** partially true rather than wholly. `MessageView::updateHeader()`
(`src/messageview.cpp:219`) shows only the thread subject and a message count.
Per-message From and Date *are* rendered inside the HTML body as `.msg-header`
(`src/htmlbuilder.cpp:241`), styled at 9pt grey, which is easy to miss and does
not include To or Cc at all.

**Check before building:** does `MimeParser` already extract To and Cc into the
message struct, or does `src/types.h` / `MimeParser`'s output need extending
first? If the fields are not parsed, that is the real first task and it is
larger than the UI work.

**Answered, 2026-08-04: they are already parsed.** `MimeParser::parse()` fills
both (`src/mimeparser.cpp:344-345`, into `ParsedMessage::to` and `::cc`,
declared at `src/mimeparser.h:105`). The larger task the check warned about
does not exist.

They are parsed and then **dropped at the renderer**: `HtmlBuilder` interpolates
only `from`, `subject` and `date` (`src/htmlbuilder.cpp:216`, `:244-245`), and
`to`/`cc` appear nowhere in it, in `messageview.cpp`, or in `mainwindow.cpp`.
So this is UI work only, as the item's own two-part approach assumes.

**Approach, two parts:**

- Widen the persistent header at the top of the message pane to show the
  selected message's From, To, Cc, Date and Subject. This is the note's stated
  preference ("should appear on top in right pane").
- Add a shortcut and menu entry for a full raw-header dialog, for the cases the
  summary omits (Message-Id, List-Id, Received chain). Read-only, selectable
  text, no rendering.

Both, not one: the header widget answers "who is this from" at a glance, the
dialog answers "what actually happened to this message". They are different
questions.

### Decided (user, 2026-08-04): the header adapts to the item count

The pane shows a thread, not a message, so From/To/Cc are per-message while the
header is one strip. Rather than pick a message arbitrarily, the header shows
only what it can say honestly:

- **One message in the thread:** From, To, Cc, Subject. The natural spot, and
  every field is unambiguous.
- **N messages:** Subject and the thread count. Nothing more.
- **Everything else** lives in the popup, reached by a **button on the right of
  the header** plus a keyboard shortcut.

**No recipient line on a thread (user, 2026-08-04).** An earlier draft of this
decision put To on the thread header too, which forced a choice between the
union of recipients and their intersection: once the user has replied, message
1 is To: them and message 2 is To: the other party, so the intersection is
frequently empty and the union is really a participants list wearing the wrong
label. The user's call was that this is overcomplicating, and it is: the
per-message detail is what the popup is for.

The thread header therefore keeps showing exactly what it shows today, subject
and count (`MessageView::updateHeader()`, `src/messageview.cpp:259`), and only
the single-message case gains fields.

**Consequence: no address parsing is needed.** `ParsedMessage::to` and `::cc`
are raw header strings (`src/mimeparser.h:104-105`), and with no union or dedup
to compute they can be displayed as they stand. Splitting them into address
lists, which would have needed GMime's `internet_address_list_parse` to survive
a display name containing a comma, is not part of this item.

**Deferred, not rejected (user, 2026-08-04): a participants line for threads.**
The union-of-recipients idea is worth revisiting as its own pass, where it can
be designed as a participants list rather than smuggled in under a "To:" label
that misdescribes it. It needs the address parsing above, so it is a genuine
piece of work rather than a display tweak. Build this item as specced first.

**Noted for later, not now:** the user's mental model of the thread view
differs from what was built. That is a separate refactor and should not be
folded into this item.

**Constraint:** header values are untrusted input. The existing header label is
`Qt::RichText` (`src/messageview.cpp:104`), so every value must be
`toHtmlEscaped()` before interpolation, exactly as `updateHeader()` already
does. A `From` display name containing markup must never be able to inject into
the label. The raw-header dialog should use `Qt::PlainText` and sidestep the
question entirely.

### Outcome (done)

Built as decided. `MessageView::updateHeader()` branches on the item count: one
message shows From, To and Cc under the subject, several show the subject and
the count exactly as before. `showDetailsDialog()` lists every message's
Subject, From, To, Cc, Date and Message-Id, numbered when there is more than
one, in a read-only `QPlainTextEdit`. A `Details...` button sits to the right of
the header, and `message_details` binds it to `Ctrl+Shift+D` (shifted because
`Ctrl+D` is delete, and the destructive binding keeps the key it had).

- **Rendered and inspected**, not only asserted: both header shapes were grabbed
  to PNG and looked at. The single-message case shows three rows under the
  subject, the thread case shows the count and no recipients.
- **An empty Cc omits its row** rather than printing a label with nothing after
  it, which reads as a rendering fault.
- **A test caught a latent flaw in an older test.** `attachmentButtonLabels()`
  identified attachment buttons by excluding the one other button's label, so
  the new details button was counted as an attachment the moment it existed.
  It now finds the bar by object name and looks only at its children, which is
  what it should have done: an exclusion list silently adopts every button
  added later.

**No address parsing was needed**, as the decision above anticipated. The header
prints `ParsedMessage::to` and `::cc` as they stand.

## 3, 8, 9. Discoverability: menu bar, toolbar, shortcut reference

Grouped because they are one piece of work. Item 3 is the complaint, items 8
and 9 are two of its symptoms.

**Observed:** for a GUI app there is almost nothing to click; every action needs
a memorized key. Archive and undo have no buttons. There is no way to see the
configured bindings without opening a terminal.

**Cause:** `MainWindow` has no `menuBar()` and no `QToolBar`. Actions are not
`QAction`s at all: `registerActions()` (`src/mainwindow.cpp:209`) fills a
`QHash<QString, std::function<void()>>` consumed by an `eventFilter`. Nothing in
that structure can appear in a menu, because a menu needs `QAction` objects.

**Approach: convert the action registry to `QAction`s.** This is the core of the
work and everything else follows from it.

- Each entry becomes a `QAction` with text, an object name matching the current
  action key, and a shortcut set from `KeyMap`.
- `MainWindow::registeredActionNames()` and the `KeyMap::knownActions()` drift
  test (already noted in `mainwindow.h` as hand-maintained) must keep working.
  If the conversion lets both lists derive from one source, that test becomes
  unnecessary, which is a real win. Check whether it can.
- The `eventFilter` route may become redundant once shortcuts live on the
  `QAction`s. Removing it is the goal, but verify: the filter may be handling
  focus cases (keys while the query line edit has focus) that `QAction`
  shortcuts resolve differently. Do not delete it on the assumption that
  `QAction` covers everything.
- Menu bar: File (Sync, Quit), Edit (Undo, Redo), Message (Archive, Delete,
  Spam, Toggle unread, Toggle HTML, Load remote content), View (font size, see
  item 4), Help (Shortcuts, About).
- Toolbar: the frequent subset only. Sync, Archive, Delete, Undo. A toolbar
  holding every action is as unreadable as no toolbar.
- Shortcut reference (item 9): a dialog listing action, description, and current
  binding, generated from the same `QAction` list. Generated, never hand-written
  in parallel, or it drifts the way the two action lists already do.

**Constraint:** undo must stay unconfirmed. `CLAUDE.md` is explicit that tag
mutations get undo instead of confirmation dialogs. Adding menu entries must not
smuggle in a "Are you sure?" for Delete.

**Verification:** the existing keymap test must still pass unchanged, proving
user bindings survive the conversion. That is the load-bearing check here.

### Outcome (done)

Built as described: menu bar, toolbar, and a generated shortcut reference.
Four things the plan did not anticipate, all verified by probe rather than
assumed:

- **The event filter was removable, but not for the stated reason.** The plan
  worried that `QAction` shortcuts might lose to `QAbstractItemView`'s
  type-to-search. They do not: shortcut dispatch runs before the focused
  widget sees the key. The filter is gone, and the thread view no longer
  needs its own.
- **Qt already solves the query-bar case.** A plain-letter shortcut is
  suppressed while an editable widget has focus, so the `hasFocus()` guard
  was unnecessary. Removing it also fixed `Ctrl+Q`, which the old filter
  swallowed while typing a query.
- **Three default bindings had never worked.** `N`, `F` and `G` stored the
  unshifted key, which no keystroke emits, so `toggle_unread`, `flag` and
  `sync` were dead in 0.1.0. Fixed in `KeyMap::normalizeSequence()` and
  committed separately from the menu work.
- **The drift test did become unnecessary**, as the plan hoped.
  `registeredActionNames()` is now derived from the `QAction`s, and
  `defaultBindings()` is the single source for the defaults. The two tests
  that pinned the hand-maintained lists together were replaced by ones that
  check a configured binding actually reaches its action.

Defaults moved to modifier shortcuts, since a single letter cannot be a menu
accelerator without claiming that letter window-wide. Existing `[keys]`
entries are unaffected.

## 4. Message-pane font size does not survive restart

**Observed:** described as "very annoying", more so than item 1.

**Confirmed by the user:** Ctrl+`+` / Ctrl+`-` do change the message pane font
size. It is only the persistence that is missing.

**Cause:** qtmaildir does not implement that zoom. There is no `setZoomFactor`,
no zoom action, and no `Ctrl+=`/`Ctrl+-` binding anywhere in `src/`; grep finds
nothing. The behavior comes from `QWebEngineView`, which handles zoom keys
natively in Chromium. `htmlbuilder.cpp:26` separately hardcodes
`font-size: 10pt` as the document's base size, which the browser zoom then
scales.

This changes the shape of the work. There is no application-side value to save,
because the application never learns the zoom changed: Chromium handles the key
and adjusts the factor without telling anyone. Persistence therefore requires
taking ownership of zoom first, rather than hooking a save onto something that
already exists.

**Approach:**

- Add explicit zoom in, zoom out and reset actions calling
  `QWebEngineView::setZoomFactor()`, tracking the current factor in
  `MessageView`. Use `setZoomFactor` rather than rewriting the CSS: it scales
  the rendered document uniformly, needs no re-render, and does not disturb
  `HtmlBuilder`'s output or its tests.
- Bind them to the same Ctrl+`+` / Ctrl+`-` the user already has in their
  fingers, so the change is invisible except that it now sticks. Verify the
  application binding actually takes precedence over Chromium's built-in
  handling; if the web view swallows the key first, the action never fires and
  the factor silently diverges from what is on screen. This is the one real
  risk in the item and is worth checking before building the rest.
- Persist the factor to the UI state file from item 1, and reapply it on every
  `setDocument()`. Do not assume zoom survives a load; `QWebEngineView` may
  reset it on navigation. Verify empirically.
- Config entry as the user suggested: a `[general]` key for the starting zoom,
  with the state file remembering runtime changes on top of it. The config value
  is the default for a fresh profile, the state file is what the user last had.
- Clamp to a sane range. An accidental 0.1 or 25.0 leaves the pane unusable and
  the user with no visible way back. Chromium's own limits are roughly 0.25 to
  5.0; match or tighten, never widen.
- Route the actions through item 3's `QAction` conversion so they appear in the
  View menu, which also makes the reset discoverable.

### Outcome (done)

Built as described, and both of the plan's stated risks turned out not to
exist. Probed rather than assumed:

- **The application `QAction` wins over Chromium's native zoom key.** The plan
  called this "the one real risk in the item". It is not one: the action fires
  and the web view's own handling never runs, so the tracked factor cannot
  diverge from what is on screen.
- **Zoom survives `setHtml()`.** The plan expected the view might reset it on
  navigation and asked for a reapply per render. Not needed; the web view keeps
  the factor, so it is the single source of truth and there is no second copy.
- **Do not test key reachability with synthetic input.** A probe using
  `QTest::keyClick()` reported `Ctrl++` as a dead binding, and a test was
  written asserting it. Both were wrong: `Ctrl++` is exactly what the `+` key
  emits on an Italian layout, confirmed against the real keyboard, and it is
  the shipped default. Whether a symbol needs Shift is a property of the
  layout, not of Qt, and `keyClick()` reproduces neither. The test now only
  checks that every default parses.
- `Ctrl+=` is a second binding for reset, skipped when `[keys]` gives `Ctrl+=`
  to something else. Ctrl+wheel zooms and Ctrl+middle-click resets, both
  filtered by ancestry from an application-level filter: the events land on an
  internal `QQuickWidget` the web view creates lazily, so a filter installed on
  the view itself never sees them.

**A pre-existing bug surfaced while adding the config key.** `[general]`
entries were read as `general/<key>`, which matches nothing: QSettings' INI
backend treats a section literally named `[general]` as its own fallback
section and strips the prefix. `notmuch_config` had therefore never worked.
Both keys are now read without the prefix; the file format the user writes is
unchanged. Regression test in `test_config`.

## 5. Thread list is cramped

**Observed:** rows are tightly packed, everything is uniform, the UI reads as
"stuffed".

**Approach:** presentation only, no model changes.

- Row height: give the `QTableView` vertical breathing room.
- Alternating row colors, or a subtle separator.
- Make unread threads visually distinct (bold), which is the one distinction
  that carries real information and currently does not exist.
- Consider dropping a column. Look at what `ThreadListModel` exposes and ask
  whether every column earns its width.

**Caution:** do not hardcode colors. The app should follow the desktop palette;
a hand-picked grey that looks right on a light theme is unreadable on a dark
one. Use `QPalette` roles. This applies to `HtmlBuilder`'s CSS too, which
currently hardcodes `#bbb`, `#555`, `#000`, `#666`, `#ddd` and no background,
and will look wrong under a dark theme. That is arguably its own item; see
item 12 below if it gets split out.

### Refined by the user, 2026-08-04

Two concrete sub-items, from using the list rather than looking at it:

- **"All items look unread (bold), maybe use regular for read items?"**
  **Check this before changing anything.** Bold is ALREADY conditional:
  `ThreadListModel::data()` sets it under `Qt::FontRole` only when
  `thread.isUnread()` (`src/threadlistmodel.cpp:148-152`). So either the
  observation is that the user's list genuinely is mostly unread, in which case
  there is no bug and the fix is elsewhere (the density work below), or bold is
  leaking onto read rows through some path the model does not control. Reproduce
  against a query with a known mix, e.g. `tag:inbox and not tag:unread`, before
  touching the font logic.

- **A star column for flagged threads**, mirroring the paperclip column that
  already exists for attachments. `ThreadSummary` carries the tags and
  `flagged` is an ordinary notmuch tag, so this needs no new worker query, the
  same way item 15's paperclip did not. Keep it narrow: an icon column, no
  text.

## 6. Opened message stays unread

**Observed:** opening a message leaves it tagged unread; the user expects it to
become read.

**Decision (user, 2026-08-03): mark read after a 2 second delay, configurable.**

**Approach:**

- A `QTimer` started in `onThreadSelected()` (`src/mainwindow.cpp:373`), fired
  once, removing the `unread` tag from the displayed thread.
- The timer **must** be restarted, not stacked, when the selection changes.
  Arrowing quickly down a list must not mark ten threads read; only the one
  still selected when the timer fires.
- **Decided (user, 2026-08-03): the automatic mark-read does NOT go on the undo
  stack.** The tag change routes through `sendThreadTagChange()` directly,
  bypassing the `ThreadTagCommand` push, exactly as an explicit non-undoable
  mutation would. Rationale: a manual toggle-unread action already exists
  (`toggle_unread`, `src/mainwindow.cpp:242`), so a user who wants the message
  back as unread has a direct route and does not need undo for it. Leaving a
  message read after undoing an unrelated archive is acceptable; hijacking
  Ctrl+Z to undo an action the user never took is not.
- Consequence to keep in mind: `applyTags` is the funnel for all mutations per
  `CLAUDE.md`, and that stays true. What changes is only whether the inverse is
  pushed onto the `QUndoStack`, which is a `MainWindow` decision made above the
  worker. Do not add a second write path to the worker for this.
- Config key in `[general]`, e.g. `mark_read_delay_ms`, default `2000`, with `0`
  meaning "immediately" and a negative value meaning "never". Document all
  three in the README.
- Interaction with item 3's toggle-unread action: if the user explicitly marks a
  message unread, the timer must not immediately re-mark it read. Cancel the
  pending timer on any manual unread toggle.

**Verification:** unit-testable against the throwaway notmuch database the
`NotmuchWorker` tests already build, but the timer logic itself is UI-side and
easier to check by hand. At minimum, verify the rapid-arrow case manually.

### Outcome (done)

Built as specced, including every decision recorded above: a 2000 ms default,
`mark_read_delay_ms` in `[general]`, the automatic change kept off the undo
stack via `sendThreadTagChange()`, and an explicit `toggle_unread` cancelling
any pending timer.

**The rapid-arrow case is unit-tested, not left to hand-checking.** The plan
expected it to need a database and a person; it needs neither. `ThreadListModel`
takes threads directly through `appendBatch()`, so a test builds three unread
rows, arrows through them, and asserts one timer stays armed. The timer carries
an object name so the test observes it through `findChild` rather than the
window exposing it.

**The three tests were verified by breaking the code**, since a passing test
proves nothing until it has been seen to fail:

- Removing the already-read check arms a timer for a read thread, caught.
- Creating a fresh timer per selection instead of restarting one, which is
  precisely the stacking the plan warns about, fails two of the three.

**Two guards the plan did not call for**, both from asking what happens when
the timer outlives its thread. `scheduleMarkRead()` refuses to arm for a thread
that is not unread, so a read thread never schedules a write that would change
nothing. `markCurrentThreadRead()` re-checks that the thread it was armed for
is still selected AND still unread before writing, so a timer that survives a
selection change or a manual toggle does nothing rather than tagging the wrong
thread.

## 7. HTML view should be default for HTML messages

**Verify before doing anything.** `MessageView::m_preferHtml` is already
initialized to `true` (`src/messageview.h`), and `clear()` resets it to `true`
(`src/messageview.cpp:164`). HTML should already be preferred where a message
offers it.

Possible explanations for the observation:

- The messages in question are `multipart/alternative` and `HtmlBuilder`'s
  `PreferHtml` mode is not selecting the HTML part correctly.
- The HTML renders, but with remote content blocked it looks like plain text.
- `m_preferHtml` is being reset between messages by a `clear()` the user did not
  intend to trigger.

Reproduce first with a specific message, then decide. If it turns out to work
correctly, the item becomes a documentation gap rather than a bug, and the
user-preference key mentioned in the note (`prefer_html`, `[general]`) is still
worth adding for people who want plain text by default.

**Do not**, in the course of this, relax anything in the web view security
section of `CLAUDE.md`. Preferring HTML is orthogonal to remote content, which
stays blocked and per-render.

### Outcome (done, 2026-08-04): nothing was broken

**Verified by the user against real mail: HTML messages do open as HTML.** The
item was raised on an observation that could not be reproduced afterwards, and
the code was already correct: `m_preferHtml` initialises to `true` and `clear()`
resets it to `true`, so every thread starts in `PreferHtml`.

No code changed. Recorded as done rather than dropped, since the behaviour the
item asked for is the behaviour that ships.

The `prefer_html` config key the item floated for people who want plain text by
default was **not** added: nobody has asked for it, and `toggle_html`
(`Ctrl+H`) already switches a thread by hand. Add it if someone wants the
default flipped, not before.

## 10. Reaching an account's inbox takes two steps

**Observed:** select account from the dropdown, then click inbox or unread.

**Approach:** cheapest useful fix first.

- Persist the selected account across restarts (uses item 1's state file). If
  the user reads one account 90% of the time, this alone removes most of the
  friction.
- Then: per-account entries in a menu, or saved queries that carry their own
  account scope, so one action gets there. `Account::scopedQuery()` already
  exists in `Config`, so the composition is available; it is a UI question, not
  a query question.

Do not build a full account sidebar for this. Persisting the selection may
resolve the complaint entirely, and it is a fraction of the work. Reassess after.

### Partly done

**The startup query is now chosen by name**, not by sort order. `[queries]` is
read through `childKeys()`, which sorts alphabetically, so the old
`savedQueries().first()` opened whichever entry happened to sort first, which
is why the app came up on Inbox. `[general] startup_query` names the entry,
defaults to `Unread`, and falls back to the first saved query when the name
matches nothing. Only a name the user wrote is worth a warning: the built-in
default naming a query they never created is not something they got wrong.

Neither half of item 10 proper is done: the account selection still resets on
restart, and reaching an account's inbox is still two steps.

### Postponed (user, 2026-08-04)

**The user does not intend to go this route as of now.** Postponed rather than
dropped: the complaint was real, and the cheap fix the item proposes (persist
the account selection across restarts) is still the right first move if it is
picked up again. Nothing here is invalidated, it is simply not wanted yet.

Only the startup-query half shipped, in 0.3.0. Do not propose the remaining
work unprompted.

## 11. Icon, `.desktop` file, SlackBuild

Packaging, independent of everything above, and can proceed in parallel.

- **Icon:** an SVG plus rendered PNGs at the standard hicolor sizes. Needs a
  design decision, not just code.
- **`.desktop` file:** `Categories=Network;Email;`, `Terminal=false`,
  `MimeType=x-scheme-handler/mailto;` only if a `mailto:` handler is actually
  implemented, which it is not in 0.1.0. Do not claim the MIME type until it
  works; a desktop entry that registers as the mail handler and then does
  nothing is worse than not registering.
- **CMake install rules:** icon into `share/icons/hicolor/<size>/apps/`, desktop
  file into `share/applications/`. Neither exists yet.
- **SlackBuild:** per the global workflow, sources are authored here and the
  user builds. Deliverables are `qtmaildir.SlackBuild`, `.info`, `README`,
  `slack-desc`, plus an nvchecker stanza. Depends on a tagged release existing
  to point `DOWNLOAD` at, so it follows a tag rather than leading it.

---

## 13. No visual feedback that an action stuck

**Observed:** selecting a thread and hitting Delete changed nothing on screen.
No way to tell whether the thread was really going to be deleted on the next
sync, which is bad UX for every tag action, not only delete.

**Cause:** not a missing update. `ThreadListModel::applyTagChange()` already
added the tag and emitted `dataChanged` across the whole row, so the Tags
column did change. But `SubjectColumn` was set to `QHeaderView::Stretch` while
`TagsColumn` came after it, so Subject absorbed all free width and pushed Tags
out of view. The feedback existed in the one column that could not be seen.

**Approach:** two changes, since the cause was two things.

- Column order is now Tags, Date, From, Subject. Subject stretches and is
  last, so nothing sits to its right to be pushed out. The other three size
  to their contents.
- A thread tagged `deleted` or `spam` styles its entire row: muted dark red
  (`#8b2c2c`) or orange (`#a85c18`) fill, white text, struck through. Applied
  through `Qt::BackgroundRole`, `Qt::ForegroundRole` and `Qt::FontRole` for
  every column, so no cue depends on a single column staying visible.

Strike-through rides along with the fill deliberately: it survives a theme
that overrides background colours, a colourblind reader, and a screenshot.
Bold for unread still composes with it.

**Decisions:** no status-bar or toast changes, the existing `tagSelected()`
message stays as it is. Archive removes `inbox` and adds nothing, so an
archived thread gets no row styling; whether it should disappear from an inbox
query is deliberately left open rather than guessed at.

**Verification:** four model tests covering the colours, the strike-through,
that styling spans every column, and that undo restores a plain row. Rendered
and inspected: normal, unread, deleted, spam, and deleted-plus-unread rows.

---

## 14. Tag column unreadable

**Observed:** with tags spelled out per row the column ran to 500 pixels of
mostly repeated text ("account-provider-work attachment flagged
inbox passed replied"), dominated by the account prefix, and consumed most of
the list's width.

**Cause:** presentation, not data. 96 tags in this database, many hierarchical
(`shopping/amazon`, `mailing-list/SBo`), rendered as a joined string.

**Approach:** the column is gone. Tags now render as coloured chips in two
places, split by taxonomy:

- The **account tag** says which mailbox a thread came from. It draws as a chip
  in front of the subject, coloured and labelled from its own `[account.<key>]`
  stanza via new `color` and `label` keys. `label` is display-only; the notmuch
  tag is never renamed.
- **Functional tags** say what state a thread is in. They fill a single row
  under the message pane, with overflow collapsing into a `+N` chip whose
  tooltip lists the hidden ones. A single row keeps the message area from
  shifting between threads with different tag counts.

Colours resolve exact tag first, then top-level prefix, so one `shopping` entry
covers the hierarchy without listing all 96. Unconfigured tags fall back to a
hash of the name, stable so a chip never changes colour as the list scrolls.

**Defect found while building:** QSettings treats `/` in a key as a group
separator, so `shopping/amazon` becomes a nested key that `childKeys()` never
returns. Reading `[tagcolors]` with `childKeys()` silently dropped every
hierarchical tag, and each fell through to its prefix colour. Fixed by reading
`allKeys()`, with a regression test. The same gotcha is already documented in
`CLAUDE.md` for `[account.work]` section names.

**Deferred:** clicking a chip to search that tag. Display only for now.

## 15. Attachments are parsed but unreachable from the UI

**Observed, 2026-08-03, with a screenshot.** A thread known to carry
attachments shows the `attachment` chip and a body that refers to them, but
there is no way to download or open one. The user also has no way to tell a
message has an attachment before opening it.

**Cause: the attachment bar is an empty placeholder.**
`MessageView` creates `m_attachmentBar` and gives it a layout
(`src/messageview.cpp:130`), adds it to the pane (`:142`), and then **nothing
ever puts anything in it**. `m_attachmentBar` appears nowhere else in the
codebase, and neither `render()` nor `showThread()` reads
`ParsedMessage::attachments`. The bar has never displayed an attachment.

This is a gap in the UI only. The backend is complete and already hardened:
`MimeParser` fills `attachments`, and `Attachment` has `safeFilename()`,
`saveTo()` and `isPathInsideDirectory()` with the path-traversal guard
`CLAUDE.md` describes. None of that work needs redoing; it needs calling.

**Approach, two independent pieces.**

- *Populate the bar.* For each attachment on each rendered message, one button
  showing the safe filename and the size. Clicking saves, through a
  `QFileDialog` for the target directory, then `Attachment::saveTo()`. Report
  the written path in the status bar, since a silent save is the same UX
  failure as item 13.
- *A paperclip column in the thread list*, so an attachment is visible before
  opening. `ThreadSummary` already carries the thread's tags and notmuch
  applies `attachment`, so the column can be driven from the existing tag data
  with **no new worker query**. Keep it narrow: an icon column, no text.

**Constraints.**

- **Filenames are untrusted.** Display `safeFilename()`, never the raw
  `filename`, and never interpolate either into rich text without escaping.
  The save path must go through `saveTo()`, which is where the boundary check
  lives.
- **Do not add "open in default application" in the same change.** That means
  handing a file from a stranger to `xdg-open`, which is a materially
  different security decision from writing it to a directory the user picked.
  If it is wanted, it is its own item with its own reasoning.
- A thread renders as one document, so the bar must make clear which message
  an attachment belongs to once a thread has several. Grouping by message, or
  a per-message row inside the HTML, are both plausible; decide when building.

**Verification:** a message with a known attachment saves a byte-identical
file. A message with an attachment named `../../etc/passwd` writes inside the
chosen directory under a sanitised name and nowhere else.

### Outcome (done)

Both halves built. The paperclip column needed no new worker query, as the
plan expected: notmuch applies the `attachment` tag itself, so
`ThreadSummary::hasAttachment()` reads what is already there.

**The bar holds ONE button, not one per file.** The plan's "one button showing
the filename and size" was built first and was wrong: a thread with sixteen
attachments made the bar as wide as the window, pushed the splitter over, and
left the thread list a few pixels wide. It is now `Attachments (N)...` opening
a dialog that lists message number, filename and size with a `Save...` each,
plus `Save all...` when there is more than one. No filename reaches the bar,
so no filename length can resize anything.

**`Save all` writes into a new subdirectory** named `<date> <subject>`, inside
a parent the user picks. Chosen over zipping: Qt ships no zip API, so a real
`.zip` meant either a new build dependency (quazip, libzip) or shelling to
`/usr/bin/zip` at runtime, and the actual requirement was "do not drop sixteen
files loose among hundreds of others". The picker's title names the subfolder
before the user commits to a location.

**Two defects found only by using it, both silent:**

- **`saveTo()` overwrites, which destroyed six of sixteen files.** Several
  messages in one thread commonly attach the same filename; each write landed
  on the previous one and every one reported success, so the status line said
  16 while the directory held 10. `saveWithoutOverwriting()` now backs the
  batch path, appending " (2)" before the extension and keeping a compound
  extension whole. `saveTo()` still overwrites, which is right for a single
  save the user just chose a location for.
- **`Qt::RFC2822Date` rejects a date carrying a timezone comment.** A header
  ending `+0200 (CEST)` is legal per RFC 5322 and common in real mail, and Qt
  refuses the whole string rather than the comment, so every such message lost
  its date prefix. Comments are stripped before parsing.

**The subject is untrusted and becomes a directory name.**
`attachmentFolderName()` lives beside the other guards in `mimeparser.cpp`,
strips separators, control characters and leading dots, caps length at 120,
and falls back to a generated name. Its test drives `../../etc`,
`/etc/passwd`, `..`, `.hidden`, a backslash and a null byte, then asserts each
result still resolves inside the parent through `isPathInsideDirectory()`.

**Deferred, as the plan required:** opening an attachment in its default
application. That hands a stranger's file to `xdg-open` and is a separate
decision from writing it to a directory the user chose.

## 16. Delete on an already-deleted thread should undelete

**Observed:** hitting Delete twice on the same message is a natural way to
express "no, put it back", but the second press does nothing visible because
adding a tag that is already present is a no-op.

**Approach:** make `delete` a toggle, the way `toggle_unread` already is.
Deleting a thread that already carries `deleted` removes it instead.

**Constraints.**

- **A multi-row selection must not split.** If some selected threads are
  deleted and others are not, toggling each independently leaves the selection
  in two states from one keystroke, which is worse than either outcome. Decide
  one direction for the whole selection: the natural rule is "if every
  selected thread is already deleted, undelete them all; otherwise delete them
  all."
- Undo already covers the mistake case, so this is a convenience, not a safety
  fix. It must not grow a confirmation dialog.
- The same question applies to `spam` and `flag`. Do not change those in this
  item; note whether the answer generalises once `delete` is built.

## 17. No completion for tags in the query bar

**Observed:** typing a query means remembering the exact tag name, including
hierarchy (`shopping/amazon`).

**Approach:** a `QCompleter` on the query bar, offering tag names after
`tag:`.

**Cause of the work being larger than it looks:** there is **no way to list
tags today**. `NotmuchWorker` has no all-tags call, so this needs a new
worker request and result signal, following the existing generation-counter
pattern. `notmuch_database_get_all_tags()` is the underlying call.

**Constraints.**

- The tag list must be fetched on the worker thread like everything else. No
  `notmuch_*` pointer crosses the thread boundary; the result is a
  `QStringList`.
- Refresh after a sync, since a sync can introduce tags. Do not refetch per
  keystroke.
- Completion should trigger on the `tag:` prefix specifically rather than on
  every word, or it will offer tag names where a `from:` value belongs.

---

## 18. No visual cue that there are unsynced edits

**Observed (user, 2026-08-04):** tagging changes the notmuch index immediately,
but nothing in the UI says those changes have not reached the mail store. The
user cannot tell, at a glance, whether quitting now would leave work stranded.

**Cause: nothing tracks it, and the obvious candidate cannot.** `MainWindow`
holds a `QUndoStack` (`src/mainwindow.h:142`) which looks like a record of
pending edits, but it is **cleared on every query**
(`src/mainwindow.cpp:805`, in the query-start path) because undo entries refer
to rows the new result set is about to discard. Tag a thread, then run any
query, and the stack is empty while the database change is still unsynced. The
same clear happens on a failed write (`:902`).

So `QUndoStack::isClean()` is **not** usable as the signal here, and neither is
`canUndo()`. This needs its own counter, one that only a successful sync
resets.

**Approach:**

- Count confirmed mutations, incremented where `tagsApplied` is handled (the
  same place that already clears `m_pendingChange`), and reset to zero on
  `MailSync::finished(true, ...)`. A count, not a bool, so the indicator can
  say how many.
- Show it in the status bar, next to the existing sync status rather than as a
  new widget competing with it. Wording should name the unit the user thinks
  in: threads or messages changed, not "mutations".
- Nothing modal, nothing blocking. This item is the passive cue only; the
  question of interrupting the user belongs to item 19.

**Constraints:**

- **A failed sync must not clear the count.** `finished(false, ...)` means the
  edits are still unsynced, and clearing there would assert the opposite.
- The count must survive a query, which is the whole reason it cannot ride on
  the undo stack. Do not tie its lifetime to the model.
- An external `notmuch new` from the user's cron can sync changes without the
  app knowing. The count is therefore a lower bound on confidence, not a
  guarantee, and the wording should not promise more than it knows.

**Verification:** tag a thread, run an unrelated query, confirm the cue
survives. Then sync and confirm it clears. Then make the sync fail and confirm
it does not.

## 19. No prompt to sync on exit when edits are pending

**Observed (user, 2026-08-04):** quitting with unsynced edits is silent. The
user asked for a blocking prompt offering to sync first, and suggested a
`sync_on_exit` config option.

**Depends on item 18.** Both need the same "are there pending edits" counter,
and 18 establishes it. Build 18 first; this is the interruption layer on top.

**Cause:** `MainWindow::closeEvent()` (`src/mainwindow.cpp:145`) saves UI state
and accepts unconditionally. It never consults sync state, and cannot today,
for the reason item 18 documents.

**Approach:**

- On close with a non-zero pending count, a modal question: sync now, quit
  without syncing, or cancel. Three options, not two: a user who hit Quit by
  mistake needs a way back that is not "sync".
- `[general] sync_on_exit`, as the user suggested. Sensible values are `ask`
  (default, the prompt above), `always` (sync without asking), and `never`
  (quit silently, today's behavior). A bare true/false cannot express all
  three.
- Choosing to sync means the window must stay alive until `MailSync::finished`
  arrives, since killing the process mid-sync is exactly the data loss the
  prompt exists to prevent. Ignore the close event, show progress, and close on
  the finished signal.

**Constraints:**

- **This is not a destructive-action confirmation** and does not contradict
  `CLAUDE.md`'s rule against those. That rule is about tag mutations, which
  keep undo instead of a dialog. This asks about *losing* work at a point where
  undo no longer helps, which is the opposite situation.
- A sync that fails on exit must not silently discard the user's choice. Report
  it and leave the window open rather than quitting as if it had worked.
- Quitting must remain possible when the sync command is not configured at all.
  `MailSync::isAvailable()` is already false in that case, so the prompt should
  degrade to a plain warning with no sync option rather than offering one that
  cannot run.

**Verification:** by hand. Tag, quit, take each of the three branches. Then set
each `sync_on_exit` value and confirm the behavior matches. Then quit with a
deliberately broken sync command and confirm the app neither hangs nor lies.

## 20. Thread view does not match the user's mental model

**Observed (user, 2026-08-04), in passing while deciding item 2:** "My view for
the thread visualization was different than what was built, but that's ground
for a small refactor later."

**Unspecified on purpose.** What the user pictured has not been described yet,
so there is nothing here to design against. Recorded now only so the remark is
not lost, and because item 2 touches the same surface and might otherwise be
mistaken for having addressed it.

**What exists today**, as the starting point for that conversation: a thread is
one HTML document in one web view, messages stacked in chronological order,
each with a small grey `.msg-header` carrying From and Date
(`src/htmlbuilder.cpp:241`). Messages that did not match the query render as
stubs (`MessageRef::matched`, `src/types.h:63`). It is deliberately flat:
`CLAUDE.md` records that reply structure is available from notmuch but is not
drawn as an indented tree.

The single-document design is not incidental and constrains any redesign: a
`QWebEngineView` per message would spawn a Chromium render process each, which
is why the thread is one document and why `cid:` references are namespaced per
message. A refactor that splits messages into separate views has to answer that
cost first.

**Next step: ask the user what they pictured** before proposing anything. Do
not design this item from the description above, which says only what is,
not what was wanted.

## 21. Default shortcuts are not sensible enough

**Observed (user, 2026-08-04):** "improve the default shortcuts to some sensed
defaults."

**Unspecified in detail**, so ask which bindings feel wrong before proposing a
table. What is worth recording is the history, because the defaults have
already moved once and the reasons still constrain any second pass.

**Where the current defaults came from.** 0.1.0 used bare letters. They were
replaced in the 0.2.0 menu work for two reasons that have not gone away: a
single letter cannot be a menu accelerator without claiming that letter
window-wide, and a bare capital such as `N` parses to an unshifted `Key_N`,
which no keystroke emits, so `toggle_unread`, `flag` and `sync` were dead keys
that appeared to be bound. See `KeyMap::defaultBindings()` and
`normalizeSequence()`.

**Constraints on any new default.**

- **Do not test reachability with synthetic input.** `QTest::keyClick()` does
  not reproduce a keyboard layout: it reported `Ctrl++` as dead when it is
  exactly what the `+` key emits on the user's Italian layout. Verify against
  the real keyboard, as `CLAUDE.md` records.
- Every binding is overridable in `[keys]`, so this is about what a fresh
  install feels like, not about what is possible.
- `Return` is a special case already resolved: it belongs to `open_thread` but
  the query bar claims it back while focused, so a proposal that moves it must
  not resurrect that bug.

## 22. Translatability audit and i18n wiring

**Observed (user, 2026-08-04):** "a full check of the codebase and wiring up of
the i18n system."

**This is a debt `CLAUDE.md` already records.** The rule that every user-facing
string must be wrapped in `tr()` was added while building query completion, and
that file states plainly that "pre-existing code has not been audited against
this rule". This item is that audit, plus the loading machinery which does not
exist at all.

**Two halves, and they are different sizes.**

- *The audit.* Every user-visible string in `src/` checked for `tr()`, with the
  translation context correct: a string in a free function needs
  `Q_DECLARE_TR_FUNCTIONS`, since calling `QObject::tr()` compiles but files it
  under the wrong context. `lupdate` output is the evidence here, not reading.
- *The wiring.* Nothing loads a `.qm` file today: there is no `QTranslator` in
  `main.cpp`, no `.ts` files in the tree, and no CMake rule to build or install
  them. Until that exists, a translated string has nowhere to come from.

**Constraint:** query syntax is not user-facing text. notmuch keywords such as
`tag:` and `date:` are wire format and must never be translated, only the prose
describing them. The completion vocabulary is exactly this trap: the values are
literal, the descriptions are prose.

**Verification:** run `lupdate` and read the generated `.ts`. A string that
does not appear there is not translatable, whatever the source looks like.

## 23. No way to save a search query from the UI

**Observed (user, 2026-08-04):** saved queries live in the config file only.
There is no way to keep a query you have just written without editing
`qtmaildir.conf` by hand.

**Approach, and one real design question.**

- A "save this query" action that names the current query bar contents and adds
  it to `[queries]`.
- The user's own suggestion for presentation: **a few sensible ones as buttons,
  the rest behind a menu.** Today `SavedQueryBar` shows them all, which does not
  scale past a handful.

**The design question is where the write goes.** `qtmaildir.conf` is hand-edited
and owned by the user, and item 1 established the rule that machine-written
state belongs in `uistate.conf` instead, precisely because QSettings preserves
neither comments nor key order and would quietly reformat the file on write.
Saved queries are not machine state though: they are user intent, they belong
with the hand-written ones, and splitting them across two files so the UI can
avoid touching one would be worse than either option. Decide explicitly, and
say so in the README whichever way it goes.

**Relation to item 10.** Item 10 is postponed, but its second half proposed
exactly this: "saved queries that carry their own account scope, so one action
gets there". If saved queries gain an account scope here, item 10 may be
answered as a side effect rather than needing its own work.

---

## Deferred, unsized, or split out

Items noted while triaging but not part of the original list. Same numbering
sequence, appended as they arise.

| # | Item | Why here |
|---|------|----------|
| 12 | `HtmlBuilder` CSS is light-theme only | Split from item 5. Hardcoded greys and no background color; a dark desktop theme will render message bodies badly. Fix likely means passing palette-derived colors into the CSS, which affects `HtmlBuilder`'s tests. |

## Adding to this document

Append a row to the status table with the next free number, then a section using
the same shape: **Observed** (what the user saw), **Cause** (the code, with file
and line, verified not assumed), **Approach**, **Constraints**, and
**Verification** where it is not obvious. Do not renumber. Do not delete: mark
`dropped` with a reason.