docs: spec the saved-query file, and reduce item 23 to a pointer

Item 23 had grown past what a backlog entry should hold: a storage format, a
migration, a dialog and a layout change. This document's own rule says a fully
specified item moves to specs/ and leaves behind the two or three things that
decide whether it can be picked up, the way items 53, 63 and 76 went. The entry
now carries the observation, the three deciding constraints and the relation to
item 10, and points at the spec for the rest.

The spec pins what was still loose. The JSON is an ordered array, since the
ordering is the whole reason for moving off [queries], and nothing may sort it
on load. A query's account scope stores the account KEY, the INI group suffix,
rather than the maildir path, so it does not duplicate config that already lives
in one place and go stale when the user edits it; the scope then composes
through Account::scopedQuery(), whose parenthesisation is load-bearing for the
same reason it is in the rules hook, an unparenthesised disjunction escapes its
scope and matches every account.

Migrated entries are pinned, so the query row does not silently empty on the
first run after upgrade, and migration order is alphabetical because that is
genuinely all the INI knows. Sent stays out of the file: it is generated from
allSentQuery() rather than stored, and folding it in would mean writing a
per-account path query into stored config, which is the duplication the
account-key decision just rejected.

The testing section is written against the traps already recorded in CLAUDE.md.
The migration test asserts the INI file is byte-identical rather than re-reading
it through QSettings, which would pass against a rewrite that preserved values
while dropping comments; the round-trip test asserts order, which is the
property the INI could not provide; and the dialog is left to a hand test,
because the offscreen platform cannot assert sizing at all and a Cancel goes
through done(int) rather than closeEvent.

Every code reference in the spec was checked against the files rather than
copied from the entry.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

1 files changed, 28 insertions, 105 deletions

diff --git a/docs/superpowers/plans/2026-08-03-post-0.1.0-usability.md b/docs/superpowers/plans/2026-08-03-post-0.1.0-usability.md
index 5faf859..268dbb4 100644
--- a/docs/superpowers/plans/2026-08-03-post-0.1.0-usability.md
+++ b/docs/superpowers/plans/2026-08-03-post-0.1.0-usability.md
@@ -87,7 +87,7 @@ taking that too literally.
 | 20 | Thread view does not match the user's mental model | presentation | L | **done** 2026-08-10, as the card list; see 53 |
 | 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, specified 2026-08-13. Saved queries move to `queries.json`, which carries order, `pinned` and account scope; wants a spec before building |
+| 23 | No way to save a search query from the UI | workflow | M | open, specified 2026-08-13; see `specs/2026-08-13-saved-queries-design.md`. Saved queries move to `queries.json`, carrying order, `pinned` and account scope |
 | 24 | No right-click actions on the thread list | discoverability | S | **done** |
 | 25 | No select-all, and bulk actions are undiscoverable | workflow | S | **done** |
 | 26 | No way to add or remove an arbitrary tag from the UI | workflow | S | **done** |
@@ -145,7 +145,7 @@ taking that too literally.
 | 78 | No way to build a rule from something visible in a message | workflow | M | open; wants 76 first, so the created rule lands in a form that can hold it |
 | 80 | A rule with many conditions squeezes the rule list to one visible row | defect | XS | **done** 2026-08-13 on `rule-builder`, unreleased. Follows item 76 |
 | 79 | Opening the rules dialog and saving destroys the first rule | defect | XS | **fixed on `rule-builder`** 2026-08-13, unreleased. Shipped in 0.16.0; damaged one real rule, repaired by hand |
-| 81 | No way to turn a saved query into a tagging rule | workflow | S | open; split out of 23 on 2026-08-13 and depends on it. Writes to the shared rules file, so it spans this repo and `mailctl` |
+| 81 | No way to turn a saved query into a tagging rule | workflow | S | open; depends on 23, which builds the dialog, and is excluded from its spec on purpose. Writes to the shared rules file, so it spans this repo and `mailctl` |
 
 Sizes are rough: XS under an hour, S a sitting, M a session.
 
@@ -213,112 +213,35 @@ does not appear there is not translatable, whatever the source looks like.
 
 **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.
-
-**Design (user, 2026-08-13).** The user described the shape they want, which is
-more specific than the original sketch and settles the file question below.
-
-- A **Save query** button beside the search bar. It opens a dialog on the
-  current query bar contents, where the query gets a **name**, an **account
-  scope**, and whatever else is worth editing before it is kept.
-- **Two tiers, presented differently.** Queries like Inbox and Unread stay
-  visible as buttons; user-made ones like "all messages from one correspondent"
-  go behind a menu. Today every entry in `[queries]` becomes a button
-  (`src/mainwindow.cpp:557`), which is the thing that does not scale.
-- If the tiers split, **the button row moves to a row of its own**, rather than
-  sharing the query row with the account box, the sort dropdown and the query
-  bar.
-
-**There is no built-in default set.** Nothing in the code distinguishes a
-default query from a user-made one: every entry in `[queries]` is user-written
-config and is rendered identically. Sent is the lone exception and is not in
-`[queries]` at all, it is built from `allSentQuery()`
-(`src/mainwindow.cpp:579`). So the two tiers need a mechanism that does not
-exist yet.
-
-**Decision (user, 2026-08-13): saved queries move out of the INI into
-`~/.config/qtmaildir/queries.json`.** The user proposed it by analogy with the
-rules file, and it is a better answer than the two the entry had considered (a
-per-query `pinned` flag inside `[queries]`, or a `[general] pinned_queries`
-list). It solves three things at once where those solved one each.
-
-- **Order.** `[queries]` is read through `childKeys()`, which returns keys
-  alphabetically and not in file order, so button order is alphabetical today
-  and cannot be chosen. `src/config.cpp:401` already records that a hand-rolled
-  parser would be needed to change it. A JSON array is ordered intrinsically,
-  so the row of buttons can be arranged.
-- **The `pinned` flag**, which decides the two tiers.
-- **Per-query account scope**, which the save dialog wants and which
-  `SavedQuery` (`src/config.h:99`) has no room for: it is `{name, query}` and
-  nothing else.
-
-**Take the shape of `rules.json`, not its machinery.** That file is JSON because
-it has TWO independent implementations that must agree, this repo and mailctl's
-`mailrules.py`; the unknown-field preservation and the `kFormatVersion`
-handshake exist to stop two programs destroying each other's writes. Queries
-have exactly one reader, so copying that wholesale would import the ceremony
-without the reason for it. What is worth carrying across is a versioned document
-read and written by one class, preserving unknown fields on the way through so a
-field added later is not stripped by an older build.
-
-**Migration: read `[queries]` once, write the JSON, and leave the INI section
-alone.** `[queries]` exists in the user's live config and in the README, so it
-cannot simply stop being read. On a run where `queries.json` is absent, the
-section is read, converted and written out; from then on `[queries]` is ignored
-entirely. **Do not strip the section:** removing it means rewriting the
-hand-edited file with QSettings, which drops comments and key order across the
-WHOLE file and is exactly the loss this decision avoids. Leaving it costs a few
-stale lines the user can delete by hand, and keeps a downgrade working. The
-README should mark it legacy. Reject the third option, reading both forever:
-two sources of truth for one thing, with no answer for which wins on a name
-collision or where the dialog writes.
-
-**This retires the entry's original open question.** It asked whether the write
-went to `qtmaildir.conf` or `uistate.conf`, and both answers were poor: the
-first machine-writes a hand-edited file, the second files user intent as window
-state. A machine-written JSON document beside the hand-written INI is the
-cleaner split, and the README caveat about losing comments goes away with it.
-The file belongs in `~/.config/`, not `~/.local/state/`: it is the user's
-intent, hand-editable, and belongs in a config backup, which a state directory
-is commonly excluded from.
-
-**"Save as a filter" is deliberately not part of this item.** The user raised it
-as an option: the same dialog could write the query out as a tagging rule, the
-reverse of item 77's Preview in list. It is left out because a rule is not a
-view. Rules live in `~/.config/mailrules/rules.json`, which has two independent
-implementations that agree by test rather than by shared code, and a `post-new`
-hook applies them to real mail every ten minutes. Writing one is a two-repo
-commitment with a live blast radius, and folding it in here would make a
-presentation change carry that risk. It is item 81.
+`qtmaildir.conf` by hand. Underneath it, every saved query becomes a button
+(`src/mainwindow.cpp:557`), so the query row grows without bound and cannot tell
+Inbox from a one-off search.
+
+**Specified 2026-08-13. Read
+`specs/2026-08-13-saved-queries-design.md` instead of planning from here.**
+
+The three things that decide whether this can be picked up:
+
+- **Saved queries move out of `[queries]` into
+  `~/.config/qtmaildir/queries.json`**, gaining an order, a `pinned` flag and a
+  per-query account scope. The INI cannot express order at all: `childKeys()`
+  returns keys alphabetically and `src/config.cpp:401` already records that a
+  hand-rolled parser would be needed to change it.
+- **It stays a single-repo change.** The format takes the shape of `rules.json`,
+  a versioned document preserving unknown fields, but none of its
+  two-implementation machinery, because queries have one reader.
+- **`startup_query`'s fallback changes meaning**, from alphabetically-first to
+  first-in-the-user's-order. User-visible, so this is a minor bump and wants a
+  changelog line. The README documents `[queries]` in three places, one of which
+  explains the alphabetical ordering this removes.
 
 **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". The 2026-08-13 design puts account scope in the save dialog
-outright, so item 10's remaining complaint is answered as a side effect rather
-than needing its own work. `Account::scopedQuery()` (`src/config.cpp:42`)
-already composes the scope, so this is a UI question, not a query question. Do
-not reopen item 10 to do it: the user postponed it and asked that the remaining
-work not be proposed unprompted.
-
-**Constraint:** the button row is built inline in `MainWindow`
-(`src/mainwindow.cpp:554-587`). There is no `SavedQueryBar` class and there
-never has been, whatever an older revision of this entry said. Moving the
-buttons to their own row is a change to that layout code.
-
-**Constraint: `startup_query` names a saved query by name**, and resolves
-against the list with a case-insensitive match plus a fallback to the first
-entry (`Config::startupSavedQuery()`, `src/config.cpp:422`). It must keep
-resolving across the migration, which also means the "first entry" fallback
-stops meaning "alphabetically first" and starts meaning "first in the user's own
-order". That is an improvement rather than a regression, but it changes which
-query a config with an unmatched `startup_query` opens on, so it is a
-user-visible change and belongs in the changelog.
-
-**Constraint: the README documents `[queries]` in three places** (the
-`startup_query` note at :109, the sample config at :194, and the query-row
-description at :256), including a line explaining that buttons appear in
-alphabetical order rather than file order. That explanation is exactly what this
-change removes, so all three need revising, not just the sample.
+gets there". The account scope in the save dialog answers it as a side effect.
+Do not reopen item 10 to do it: the user postponed it and asked that the
+remaining work not be proposed unprompted.
+
+**Item 81 depends on this** and is deliberately not part of it.
 
 ## 36. `test_mainwindow` cannot reach the worker