docs: attach files from the chat through an in-card picker

A system file dialog would open under the overlay that holds the keyboard,
so the picker is drawn in the card, over the transcript, from
Qt.labs.folderlistmodel.

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

1 files changed, 27 insertions, 1 deletions

diff --git a/docs/superpowers/specs/2026-10-16-file-drop-design.md b/docs/superpowers/specs/2026-10-16-file-drop-design.md
index d3c8a9d..289d3e8 100644
--- a/docs/superpowers/specs/2026-10-16-file-drop-design.md
+++ b/docs/superpowers/specs/2026-10-16-file-drop-design.md
@@ -53,6 +53,30 @@ animates (about 180 ms) between states, growing from the centre.
 Sent files show as chips under the question in the transcript, with the
 `truncated` mark from the daemon's `files` list.
 
+## Attaching from the chat
+
+An attach button, the paperclip `U+F0C6` (nf-fa-paperclip, present in
+Inconsolata Nerd Font, checked against its cmap), sits left of the input
+in the file and chat states. It opens a picker drawn inside the card. A
+system file dialog cannot be used: the card is an overlay layer surface
+holding the keyboard, so a dialog window, Qt's or the portal's, would open
+beneath it out of reach. Modesty draws its own picker for the same reason.
+
+- **The panel** slides over the transcript like History: a path bar with
+  Home and an up button, a filter field narrowing the current directory as
+  you type, and a list from `Qt.labs.folderlistmodel` (installed), folders
+  first.
+- **Choosing.** A click on a folder enters it; a click on a file stages it
+  as a chip and closes the panel; Ctrl+click stages and keeps it open, for
+  several files. Up and Down move the highlight, Enter opens it.
+- It opens in the directory last picked from, `~` the first time. Hidden
+  files are listed only when the filter starts with `.`.
+- **Escape** closes the picker first, then History, then the card.
+- **In the chat state** the staged files sit as chips above the input and
+  the next `ask` carries them in the same conversation; there is no file
+  state there. A chip of a kind chat does not take disables Send until it
+  is removed, as in the file state.
+
 ## File kinds
 
 `desktop/assistant/Files.js` maps a path to `text`, `image`, `pdf`,
@@ -89,4 +113,6 @@ regions, which is why the drop begins on the sliver.
   the file state; remove the chip and get entry; drop again and use Chat
   about it; ask about a PDF and an image; see chips in the transcript;
   drop a video and see the refusal; SUPER+Home after more than 10 minutes
-  gives entry, within 10 minutes the chat.
+  gives entry, within 10 minutes the chat; in a chat, the paperclip picker
+  stages one file by click and two by Ctrl+click, and Escape closes the
+  picker before the card.