chat: the @ list finds every open conversation, on every box, with spaces in the search

docs/changes/unreleased/1725-mention-list-recents-and-chat-scope.md

@@ -0,0 +1,27 @@
+---
+kind: fixed
+title: the @ list finds recent conversations on every box without taking over prose
+pr: 1725
+surface: [chat, docs]
+invalidates:
+  - "The `@` list's recent conversations were read once per process, so a conversation started in another window after the first `@` was never on it. They are read once per opening on every box when no read is pending: a new `@` token, typed or pasted, or the list returning on the next letter after `esc`. Openings during a read share one follow-up."
+  - "`@chat:` and `@team:` kept the first eight rows of their section and showed no sign of more. A prefixed list keeps up to thirty-two and scrolls; the bare `@` still keeps eight per section."
+  - "The manual did not say which conversations the `@` list holds. It does: every open tab except the one you are in and the window's own unnamed, unsent front, then the twenty most recent in this project; open tabs from other projects are included too; older or other-project saved conversations use `/resume` unless already open here."
+  - "On the new-chat page (`+`), the `@` list left off the conversation the window came from, as though you were typing inside it, so `@chat:kim` beside a lit `tell me about kim jung il` said `no conversation matches`. The start page leaves no eligible conversation off."
+  - "A prefixed `@chat:who is` search closed at its first space. `@team:`, `@chat:` and `@file:` now hold up to three spaces and match every word in any order on teams, conversations and files. A bare `@` still ends at its first space, so ordinary prose never reopens the list. A multi-word search with no match closes only after its catalog has been read."
+  - "Home's `@` list offered files alone, and `@chat:` typed there answered `no file matches`. Home's list has the same teams and conversations sections and the same `@team:`, `@chat:` and `@file:` prefixes as a conversation's box, and leaves no eligible conversation off."
+  - "Home's `@` list could clear its paths under already-ranked rows and crash, including on dev. It now walks the pinned target or this window's file root, never the row selected before opening. Locally the list, foot and sentence use the same folder; over `--host` the unpinned list walks this machine's folder like a conversation's list, while the foot and send keep the far workspace. Catalogs and rows change together; old-folder answers are ignored; closed-list arrows preserve the completed walk."
+  - "A pasted opening could skip the fresh recent read when an earlier catalog matched nothing. A new token now asks for fresh recents exactly once, even when its unmatched display closes; openings during a pending read share one follow-up, keeping at most one walk in flight per window; the earlier answer never settles their search as fresh; letters and caret moves within that opening never restart the read or repeat the opening notice. Dismissing it with `esc` ends the opening on every box; a space or punctuation keeps even a bare `@` closed without a read; the next letter brings it back with one fresh read and one opening notice. Prefixed multi-word chat searches wait for their token's answer."
+  - "Recent rows or a file walk could move the chosen row before Enter, and home's arrows left its completion cursor behind. Data arrivals select the best match unless the person chose a row since the query last changed; that choice survives while still offered. A changed query returns to the best match."
+  - "Emptying home's box skipped completion sync and kept its list open, so the next token could miss conversations started in another window. Every edit now syncs the token, including the empty box; the next `@` asks for fresh rows."
+  - "Recent-row canonicalization walked the disk on the update loop. Keys now travel with the off-loop read, preserving symlink deduplication and the hosted cleaned-path rule."
+  - "Punctuation after a chosen mention reopened an empty list, and home could draw chosen teams plain from a stale conversation catalog. Punctuation keeps the list closed; every box draws the current team colour, and plain draft rows allocate nothing for team painting."
+  - "An unsent shell could appear on the `@` list under its draft's tab name and supply an empty digest. Only the window's own unnamed front with no user entry or opening prompt is left off for having nothing sent. Every held, restored or side tab is offered without title/opening heuristics, including an untitled conversation whose first user message was a queued follow-up."
+---
+
+Santosh's report (2026-09-30): a tab reading `cloudfl…` was on the strip and
+`@chat:cloudfl` did not list it. The match itself was fine; what the list held was
+not. The recent list was a snapshot taken on the window's first `@` and kept for
+the life of the process, and a section cut at eight rows said nothing about the
+rest. The conversation in front is still left off on purpose: pointing at the
+chat you are typing in is not a reference.

internal/manual/chat/attaching-files.md

@@ -559,18 +559,57 @@ Type `@` in the message box. The list under it has three words on the first row,
 **team**, **chat** and **file**, then teams, conversations, tasks, and files. Typing
 filters every section at once. `@file:` keeps only files, `@team:` only teams,
 `@chat:` only conversations. The three words are buttons: a press types that prefix,
-the word under the pointer takes a background, and the hint names the key, `click`.
+the hint says `click`.
+
+The conversations on it are the tabs open in this window, including other projects'
+tabs, except the one you are typing in. Only the window's own front conversation
+is absent for being unnamed with nothing sent, even if its draft names its tab.
+Held, restored and side tabs are offered without that check. Then come the twenty
+most recent in this project, read once per opening when no read is pending: a new
+`@` token or the next letter after `esc`. Openings during a read share one follow-up. For older or other-project conversations
+not open here, use `/resume`. The bare
+`@` shows eight of them; `@chat:` shows them all and scrolls. Home's box opens the
+same list with the same sections and prefixes, leaving no eligible conversation off.
+Files use the pinned target or workspace. Locally the foot's `project: `
+names that folder and the sentence opens there. Over `--host`, the unpinned
+list offers this machine's files, as in a conversation; the foot and sent
+sentence use the far workspace.
 
 Choosing a file still puts `@` and the path in the sentence, and nothing is read
-until the model asks. Choosing a team puts `●harbor` in the team's colour. Choosing
-a conversation puts `@handle`, or a short slug of the title when it has no handle,
-and the hint on the row is the full title. A conversation that is in no team is
-still on the list.
+until the model asks. Choosing a team puts `●harbor` in its current colour, on
+home too. Choosing a conversation puts `@handle`, or a short slug of the title when it has no handle,
+and the hint on the row is the full title. Conversations in no team are offered too.
 
-After you send, that team mark and that `@handle` stay clickable. A press on the
+## After sending a team or conversation mention
+
+After you send, a team mark such as `●harbor` and a conversation's `@handle` stay
+clickable. A press on the
 team opens the teams page with it selected. A press on the conversation opens it. Over
 `--host`, against an engine with no teams doors, a press on the team opens the
 conversations view on it instead. The
 model is handed a short digest of each one, not the transcript, and the other
 conversation is not messaged and not woken. The words in your transcript are the
 words you typed.
+
+## Searching files and conversations with spaces after @
+
+A bare `@` token ends at its first space, so `ask @ben to fix` stays prose and
+Enter sends the whole sentence. `@ ` is no token. Only a prefixed search can
+hold spaces: `@file:tui3 app`, `@chat:who is` or `@team:har bor`, up to three
+spaces and never across a newline. Teams, conversations and files match every
+word in any order; only the final word may match by letters in order. Tasks keep
+their own scorer for the whole query.
+
+Recents are read once per opening when no read is pending: a new `@` token or the
+next letter after `esc`. Openings during a read share one follow-up; the older answer
+cannot settle their search. Letters, caret moves and automatic closes start no read.
+After `esc`, a space or punctuation keeps even a bare `@` closed.
+Removing the token, including clearing home's box,
+ends it; the next `@` reads again. A prefixed multi-word chat search waits with
+`looking…` for its fresh read. Several words with no match close a prefixed search
+after its catalog has been read.
+
+An arrival selects the best match unless you chose a row with the arrows since
+the query last changed; that choice survives while still offered. A changed query
+returns to the best match. On home, clicking a row inserts it immediately. A space
+or punctuation after a chosen mention keeps the list closed so you can write on.

internal/manual/chat/conversations-and-teams.md

@@ -313,26 +313,78 @@ so. An `@word` that is no member's handle is left as plain text.
 
 In the message box, `@` opens the same list files use. Teams are a section of it,
 each row a coloured dot and the team's name. Conversations are the next section:
-the ones open in this window first, then recent ones. A conversation in no team is
-on that list.
+the ones open in this window first, in the tab strip's order, then recent ones. A
+conversation in no team is on that list.
 
 The first row is the words **team**, **chat** and **file**. Each is a button with a
 background under the pointer and a one-line hint (`only teams · click`). A press
-types `@team:`, `@chat:` or `@file:`, and the list keeps only that section. Typing
-filters every section that is still showing.
+types `@team:`, `@chat:` or `@file:`, and the list keeps only that section.
 
-Choosing a team inserts `●harbor` in the team's colour. Choosing a conversation
-inserts `@handle`, or a short slug of its title when it has none, and the row's
-hint is the full title. After you send, both stay links. A press on the team opens
-the teams page with it selected. A press on the conversation opens that conversation.
-Over `--host`, against an engine with no teams doors, a press on the team opens the
-conversations view on it instead.
+Choosing a team inserts `●harbor` in its current colour, on home's box too;
+a team edit or adoption is reflected on every box.
+Choosing a conversation inserts `@handle`, or a short slug of its title when it
+has none, and the row's hint is the full title. After you send, both stay links.
+A press on the team opens the teams page with it selected. A press on the
+conversation opens that conversation. Over `--host`, against an engine with no
+teams doors, a press on the team opens the conversations view on it instead.
 
 The model receives a short digest of each reference: for a team, its members,
 handles, states and recent traffic; for a chat, its title, its state and an excerpt
 of the last reply. It does not receive the transcript. Mentioning a conversation
 does not message it and does not wake it. Your transcript keeps the words you typed.
 
+## Which conversations the @ list offers, and why the one I am in is missing
+
+The `@` list offers every open tab, including other projects, except the chat you
+are typing in. Only the window's own front is absent if unnamed with nothing sent,
+even if its draft names its tab. Held, restored and side tabs have no such
+check. Home and the new-chat page (`+` or `ctrl+t`) leave no eligible chat off: their
+sentences open a new one, so the chat behind them is a reference too.
+
+After the tabs come the twenty most recent conversations in this project. They
+are read once per opening when no read is pending: a new `@` token, typed or pasted,
+or the next letter after `esc`. Openings during a read share one follow-up; the
+older answer cannot settle their search. Letters, caret moves and automatic closes
+start no read. A prefixed multi-word chat search waits with `looking…` for its
+fresh read. Removing the token ends it; the next `@` asks again. After `esc`,
+a space or punctuation keeps even a bare `@` closed.
+Over `--host` those are the far machine's. An older conversation, or one in another
+project, is offered only if it is already an open tab here; otherwise use `/resume`.
+The same transcript appears once, even when its folder has a symlink spelling.
+
+The bare `@` keeps eight teams and eight conversations beside the tasks and files;
+`@chat:` and `@team:` keep up to thirty-two rows in their section and scroll.
+
+Home has the same sections and prefixes; its first-row words are not buttons, so
+type the prefix. Typing or pasting starts the same reads. New rows select the best match unless
+you chose a row with the arrows since the query last changed; that choice stays
+selected while still offered. A changed query returns to the best match.
+
+Over `--host`, home's unpinned file list offers this machine's files, as a
+conversation's list does. The foot and sent sentence use the far workspace.
+
+## Searching the @ list with spaces — @chat:who is
+
+A bare `@` token ends at the first space: `cc @ara on this` is prose, and Enter
+sends the whole sentence. `@ ` is no token. Spaces belong to prefixed searches
+only: `@chat:who is` finds `who is kim jong il`, `@team:har bor` finds `harbor`,
+and `@file:tui3 app` finds `internal/tui3/app.go`. The token may hold up to three
+spaces and never crosses a newline, on a conversation's box, home's box and the
+new-chat page's box.
+
+Teams, conversations and files match every word, in any order. A word matches
+by prefix, substring or letters in order; only the word still being typed
+may match by letters in order. Finished words match whole. `@chat:deploy worker`
+finds `Cloudflare worker deploy`. Conversations match their title, handle and
+slug, never their transcript. Tasks keep their own scorer for the whole query;
+they do not use this every-word rule.
+
+A prefixed search of several words that matches nothing closes after its catalog
+has been read. Before that it stays open with `looking…` and starts the read.
+One word that matches nothing says `no team matches`, `no conversation matches`
+or `no file matches`. After a chosen mention, a space or punctuation such as
+`,`, `.`, `;`, `:`, `!`, `?` or `)` keeps the list closed: you are writing on.
+
 ## Where teams are kept
 
 Teams are saved in your profile, in `teams.json`, every time one changes, and never in

internal/manual/chat/home.md

@@ -1475,19 +1475,70 @@ the keys row, over the project, with the bulb and the cross, and it appears only
 what makes each one appear and disappear, and the **disable hints** row on the Workspace
 tab that turns them off, are on the *hints and tips* page.
 
-## Typing @ on home — does the @ file list work on home, complete a path into home's box
-
-Yes, since 2026-09-22. Type `@` and a letter or two into home's box and the same list a
-conversation's box opens appears in home's column: files and folders under the folder the
-next conversation opens in (the one at the right of the keys row), ranked as you type,
-`folder` and `img` tags on the right. `↑`/`↓` pick, `enter` puts the path into your sentence
-after the `@`, and choosing a picture takes the half-typed token out and puts the picture on
-home's tray instead, saying `attached · shot.png · rides with the next conversation`. `esc`
-closes the list and leaves the word alone — and it is the innermost layer of the three esc
-walks through on home, so the first `esc` takes the list and a later one leaves home. Tasks
-are not on this list — a task pointer is minted when a conversation sends, and home has none
-yet. While the walk is still running the column reads `looking…`; with no match it reads
-`no file matches`.
+## Typing @ on home — does the @ list work on home, mention a team, a chat or a file from home's box
+
+Yes. Type `@` into home's box and the same list a conversation's box opens appears in
+home's column, with the same sections and the same prefixes. Its first row is the words
+**team**, **chat** and **file**; under them come **teams**, then **conversations**, then
+files and folders, ranked as you type, `folder` and `img` tags on the right. Their
+root is the pinned target, otherwise this window's workspace; over `--host` the
+unpinned list uses this machine's working directory, as a conversation's list does. `@team:`
+keeps only teams, `@chat:` only conversations, `@file:` only files, exactly as in a
+conversation.
+Conversations are every open tab, including other projects — then the twenty
+most recent in this project. Only the window's own front conversation is absent for being
+unnamed with nothing sent, even if its draft names its tab. Held, restored and side tabs
+are offered without that check. Recents are read once per opening when no read is
+pending: a new `@` or the next letter after `esc`. Openings during a read share one
+follow-up.
+
+`↑`/`↓` pick and `enter` puts the row in: a team as `●harbor` in the team's colour, a
+conversation as `@handle` or a short slug of its title, a path after the `@`. Choosing a
+picture takes the half-typed token out and puts the picture on home's tray instead, saying
+`attached · shot.png · rides with the next conversation`. `esc` closes the list and leaves
+the word alone. It takes the list first; a later `esc` leaves home. Tasks are not on this list — a
+task pointer is minted when a conversation sends, and home has none yet. While the walk is
+still running the column reads `looking…`; with no match it reads `no matches`, or under a
+prefix `no team matches`, `no conversation matches` or `no file matches`. On home the three
+words on the first row are not buttons: type the prefix.
+
+## Which project home's @ paths use
+
+Home's `@` files come from the target pinned with `alt+p` or `/project`, otherwise
+this window's file root. On a local window that is the workspace, the folder the
+sentence opens in and the one named after `project: ` on the keys row while the
+list is up. Over `--host`, the unpinned list offers this machine's files, as a
+conversation's list does; the foot and sent sentence use the far machine's
+workspace. The project row the cursor stood on before opening the list does not
+choose the file root.
+
+Changing the pinned project while the list is up replaces its files immediately
+and starts the new folder's walk. A late answer from the old folder is ignored.
+With the list closed, arrows across other projects leave the completed walk
+alone; opening the list again on that folder reuses it.
+
+## Searching home's @ list with spaces and writing after a mention
+
+On home, a bare `@` token ends at its first space: `ask @ben to fix` stays a
+sentence, and Enter starts the conversation with the whole sentence. `@ ` is no
+token. Only prefixed searches hold spaces, up to three and never across a newline:
+`@chat:who is`, `@team:har bor` and `@file:tui3 app`. Teams, conversations and files
+match every word in any order; finished words match whole, and only the final
+word may match by letters in order.
+
+Recents are read once per opening when no read is pending: a new `@` token or the
+next letter after `esc`. Openings during a read share one follow-up; the older answer
+cannot settle their search. Letters, caret moves and automatic closes start no read.
+After `esc`, a space or punctuation keeps even a bare `@` closed.
+Clearing the box ends the token and closes its list;
+the next `@` reads again and can offer a conversation started in another window.
+A prefixed chat search waits with `looking…` for its fresh read. Several words
+with no match close it after that answer.
+
+An arrival selects the best match unless you chose a row with the arrows since
+the query last changed; that choice survives while still offered. A changed query
+returns to the best match. Clicking a row inserts it immediately. After choosing,
+a space or punctuation such as a comma keeps the list closed so you can write on.
 
 ## How do I get back to the dashboard or the home screen from any page — press space twice