docs: document agent, chat, and api endpoints

docs/chat.md

@@ -0,0 +1,70 @@
+# Chats
+
+## Overview
+
+A **chat** is a conversation container owned by a user. Agents become chat members, receive messages, and can reply in threads. Every message a user sees belongs to a chat.
+
+Chats are either **persistent** (stored in the database) or **temporary** (in-memory only, useful for quick, unsaved conversations). Both kinds share the same features and appear together in listings.
+
+## Structure
+
+A chat contains:
+
+*   **Messages** — the conversation content.
+*   **Threads** — messages can be grouped into named threads; messages without a thread go to the chat's default thread.
+*   **Memberships** — which agents are in the chat. Every agent is created with a **main chat** it belongs to.
+
+## Messages
+
+Each message carries:
+
+*   `sender` — `'user'` or an agent id.
+*   `kind` — the message class: `message` (normal content), `log` (agent internals like reasoning), `note` (annotations), or `resource` (declarations such as remotes; not shown to agents).
+*   `subkind` — a refinement of the kind (e.g. `reasoning`, `remote`).
+*   `format` — content format hint.
+*   `threadId` — the thread the message belongs to.
+
+Message content may be a **stream** rather than a final value: the message is stored immediately with a stream reference and updated in place when the stream finishes. This is how agent replies appear progressively.
+
+## Delivery
+
+When a message is sent to a chat:
+
+*   The chat's owner is notified over their websocket connections (as an update when a streamed message settles).
+*   Every member agent is notified, except the sender itself. The agent then builds a run from the message's thread and can stream a reply into the same thread.
+*   `resource` messages are not delivered to agents — they are declarations, not conversation.
+
+## Threads
+
+Threads are lightweight sub-conversations inside a chat:
+
+*   Messages with no thread id belong to the chat's implicit **default thread**.
+*   Named threads can be created on demand; new messages open new threads implicitly.
+*   `note` and `resource` messages are attached to their thread separately from the main message list, so notes and remote declarations travel with a thread without polluting the conversation.
+
+## Reading Chats
+
+The **ChatView** is the read-side view of a chat in the backend, used both by agents (to build their message history) and by tooling:
+
+*   Loads the chat's basic data plus the most recent page of messages (`MESSAGE_PAGE_SIZE`), paging further back on demand — messages are ordered by id, which is more robust than timestamps.
+*   Groups messages into threads, keeping messages, notes, and resources separate per thread.
+*   Tracks the **current thread** (the most recently active one) and provides a debug dump of the full structure.
+
+## Lifecycle
+
+*   Chats are created with a name, description, picture, and an optional list of member agents.
+*   Agents can be added to existing chats at any time.
+*   Deleting a chat removes its memberships.
+
+## Frontend: the chat view
+
+The chat page is the live surface of these concepts:
+
+- **Messages** render with sender names resolved from the agent registry; new messages arrive over websockets, streamed content updates in place, and the user's own messages appear optimistically until the broadcast confirms them.
+- **Threads** are UI-first: "New Thread" is a local state, and the thread is only created upstream once a message is actually sent into it. Exactly one thread is open at a time — the active one — while all others collapse into preview headers; opening a preview makes that thread active. The last thread is only continued automatically while it is fresh (ten minutes), otherwise the chat starts in "New Thread" state.
+- **Composing** supports note mode, editing an existing message, and attaching a connected remote to the current thread as a resource.
+- **Runs** are tracked per message, so an in-flight agent reply can be cancelled from the chat.
+
+### Backend and frontend
+
+On the backend, chats are **storage and routing**: the App owns chat, thread and message persistence, membership, and the notification fan-out to users and agents. On the frontend, chats are **presentation and composing**: thread UX, live updates, optimistic sending, notes and edits.