docs: the chat window, the Inbox and security groups

Three of the surfaces a user asks about most had nothing in `docs/`, so the
assistant answered from guesswork: the chat itself (its two layouts, the tab
bar and what lands on which tab, every control around the composer, the slash
commands it must never forward to the model), the Inbox (why background work
asks there rather than in the chat, and that an unanswered card is a stopped
job, not a slow one), and security groups — the honest answer to "why does it
keep asking me for permission?", including what a group is *not*: not a mode,
not a data boundary, and not advisory.

Each page states the misreadings users actually arrive with, since correcting
those is most of the work; the tables list what the person is looking at, not
what the code does.

docs/chat.md

@@ -0,0 +1,80 @@
+# The chat window
+
+This is where almost everything happens, so it is the page users ask about most. It is one single chat surface that changes shape rather than two different things:
+
+- **On the home page it fills the screen** — the conversation *is* the landing page, with a short welcome and a few starter suggestions when it is empty.
+- **On every other page it docks to the right** as a side panel, so the user can watch a project, a file or a settings page while still talking. The panel can be dragged wider or narrower by its left edge, and hidden entirely with the **›** button in its header — a ✨ button then appears in the top bar to bring it back.
+
+Switching between the two is just navigation: nothing is lost, no message is dropped, the connection stays up. A user who says "my chat disappeared when I opened Files" has collapsed the panel, not lost the conversation.
+
+The **"Private to you"** chip in the header is a real statement, not decoration: a conversation belongs to the person who had it and nobody else can read it — the admin included. Anything that would put information into the shared space asks for approval first.
+
+## Tabs: several conversations at once
+
+The bar under the header holds open conversations.
+
+- **General** is always there and cannot be closed. It is the default chat.
+- **A project tab** appears when a project's chat is opened (from the project board's *Open chat*, or from the sidebar). It is that project's own conversation, with the project's folder and members already in context.
+- **The `+` button opens an extra chat** on General or on any project — a second conversation about the same thing, useful for working on two matters at once.
+- **Double-clicking a tab renames it.** Clearing the name gives back the automatic one, so the box is also the undo.
+- **The ✕ closes a tab, it does not delete the conversation.** A project chat comes back from its board with all its history; a closed extra chat is gone from the bar but not from the database.
+
+Two things are worth explaining when they surprise someone:
+
+- **The set of open tabs follows the person, not the browser.** It is stored in their own account, so the same tabs are there after a login on another device — and a second household member on the same laptop never sees them. *Which* tab is selected is per window, so two windows can sit on two different conversations.
+- **Anything arriving from outside lands on the main tab of its source**, never on an extra one: a notification from a background agent, the result of a finished background task, an incoming Telegram message. An extra chat opened with `+` is a place to work, not a mailbox.
+
+## The composer
+
+**Enter** sends, **Shift+Enter** makes a new line. Around the box:
+
+| Control | What it does |
+| --- | --- |
+| 📎 paperclip | Attach files. Dragging files onto the composer and pasting an image from the clipboard do the same thing. |
+| 👁 eye | Share what the user currently has open with the next message — see [view-context.md](view-context.md). |
+| ✨ model pill | Pin which LLM answers in *this* conversation. The list always starts with `auto`, which lets the instance pick per turn — that is the normal setting, and pinning is for "use the big one for this". |
+| 🛡 shield pill | The conversation's security group — see [security-groups.md](security-groups.md). Only shown when the person's role allows more than one. |
+| 🗑 bin | Start a fresh conversation on this tab. The old one is not deleted, but the tab moves on and the assistant starts with no memory of it. |
+| 🎤 microphone | Dictate instead of typing — see [voice.md](voice.md). On the desktop, holding **Ctrl+Space** records for as long as it is held. |
+| ⏹ stop | Appears while the assistant is working. It stops the current answer, including any tool still running under it. |
+
+Attachments are uploaded before the message is sent and shown as chips above the box; the ✕ on a chip removes one. Whether an image is actually *looked at* depends on the model answering — a model without vision gets the file's path and can open it with its file tools instead.
+
+Both pills are per conversation, not per person: pinning a model in one tab leaves the others alone.
+
+## Slash commands
+
+Typing `/` opens an autocomplete over the composer; ↑/↓ pick, Enter or Tab inserts. These are handled by the app itself and **never reach the model**:
+
+| Command | Effect |
+| --- | --- |
+| `/help` | The list of commands, including any custom ones this instance has |
+| `/clear`, `/new` | Start a new conversation on this tab |
+| `/models` | List the configured models in priority order |
+| `/model <name\|number\|auto>` | Pin the model for this conversation (the same thing the model pill does) |
+| `/context` | Tokens used by the last turn |
+| `/cost` | What this conversation has cost so far, in USD |
+| `/compact` | Summarise the conversation so far and carry on from the summary |
+| `/resettools` | Drop the tool groups activated during this conversation |
+| `/sethome` | Send background notifications to the web app rather than elsewhere |
+
+An **unknown** `/something` is answered with "unknown command" plus the help — it is never forwarded to the assistant as text, so a mistyped command costs nothing.
+
+An instance can also have **custom commands**, added as folders on the box (`commands/<name>/`) with a description and a template. Those behave differently: they expand into a normal message and the assistant answers it as usual, so it can ask follow-up questions and use tools. They show up in `/help` and in the autocomplete alongside the built-ins.
+
+`/compact` is the one worth explaining properly: long conversations eventually cost more and slow down, and compaction replaces the older part with a summary the assistant keeps working from. Nothing is deleted from the record; only what is sent to the model shrinks.
+
+## While an answer is being written
+
+- Text appears as it is produced. A **"Reasoning…"** block, collapsed by default, holds the model's thinking when the model exposes it — it is safe to ignore, and it is not part of the answer.
+- **Tool calls appear as cards** in the transcript: what was called, and its result once it comes back.
+- **A permission card appears inline** when the assistant needs approval for something mid-answer — the work waits there until it is answered. Requests raised by *background* work go to the [Inbox](inbox.md) instead, and appear above the composer.
+- Scrolling up stops the auto-follow and shows a **jump to latest** button; sending or clicking it returns to the bottom.
+
+## Common questions
+
+- *"Where did my conversation go?"* — check the tab bar and the collapsed panel first; a `/clear` or the bin button starts a new one, which looks like the old one vanished.
+- *"Does it remember what I said yesterday?"* — within a conversation, yes; across conversations only through memory (see [memory.md](memory.md)).
+- *"Can my partner/parent read this chat?"* — no. Conversations are private to the account that had them. What can be shared is what goes into shared memory or a shared folder, and that asks first. (One exception worth being honest about: if the instance has a supervision arrangement, a background agent may write a *summary* report about a supervised account — see [system-agents.md](system-agents.md).)
+- *"Why does it keep asking me for permission?"* — that is the security group, not the model being cautious: [security-groups.md](security-groups.md).
+- *"It's stuck."* — look above the composer for a waiting request, and in the Inbox; otherwise the ⏹ button ends the turn cleanly.