merge: resolve main conflicts for export-thread PR

Author: Killea

FRONTEND_TEST_PLAN.md

@@ -1,5 +1,5 @@
 # AgentChatBus 
-![bus_big](doc/bus_big.png)
+![bus_big](https://raw.githubusercontent.com/Killea/AgentChatBus/main/doc/bus_big.png)
 
 **AgentChatBus** is a persistent AI communication bus that lets multiple independent AI Agents chat, collaborate, and delegate tasks — across terminals, across IDEs, and across frameworks.
 
@@ -10,11 +10,11 @@ A **built-in web console** is served at `/` from the same HTTP process — no ex
 ---
 
 ## Screenshots
-![read_pix](doc/pix.jpg)
+![read_pix](https://raw.githubusercontent.com/Killea/AgentChatBus/main/doc/pix.jpg)
 
-![chat](chat.jpg)
+![chat](https://raw.githubusercontent.com/Killea/AgentChatBus/main/chat.jpg)
 
-![chat2](chat2.jpg)
+![chat2](https://raw.githubusercontent.com/Killea/AgentChatBus/main/chat2.jpg)
 
 *Added resume feature.*
 
@@ -95,7 +95,7 @@ pip install agentchatbus
 Optional: install a specific version:
 
 ```bash
-pip install "agentchatbus==0.1.1"
+pip install "agentchatbus==0.1.6"
 ```
 
 ### 2.1 — After pip install: how to run
@@ -223,10 +223,10 @@ Install from a GitHub Release wheel (alternative distribution path):
 
 ```bash
 # Example: install from local downloaded wheel file
-pip install dist/agentchatbus-0.1.1-py3-none-any.whl
+pip install dist/agentchatbus-0.1.6-py3-none-any.whl
 
 # Example: install directly from a GitHub Release URL
-pip install https://github.com/Killea/AgentChatBus/releases/download/v0.1.1/agentchatbus-0.1.1-py3-none-any.whl
+pip install https://github.com/Killea/AgentChatBus/releases/download/v0.1.6/agentchatbus-0.1.6-py3-none-any.whl
 ```
 
 ### 3 — Install (Source Mode, for development)
@@ -402,7 +402,7 @@ Any MCP-compatible client (e.g., Claude Desktop, Cursor, custom SDK) can connect
 
 This repository includes a release workflow at `.github/workflows/release.yml`.
 
-When you push a tag like `v0.1.1`, GitHub Actions will:
+When you push a tag like `v0.1.6`, GitHub Actions will:
 
 1. Build `sdist` and `wheel` via `python -m build`
 2. Create/Update a GitHub Release for that tag
@@ -525,20 +525,45 @@ AgentChatBus therefore exposes **underscore-style** tool names (e.g. `thread_cre
 
 | Tool | Required Args | Description |
 |---|---|---|
-| `thread_create` | `topic` | Create a new conversation thread. Returns `thread_id`. |
+| `thread_create` | `topic` | Create a new conversation thread. Optional `template` to apply defaults (system prompt, metadata). Returns `thread_id`. |
 | `thread_list` | — | List threads. Optional `status` filter. |
 | `thread_get` | `thread_id` | Get full details of one thread. |
 | `thread_delete` | `thread_id`, `confirm=true` | Permanently delete a thread and all messages (irreversible). |
 
 > **Note**: Thread state management (`set_state`, `close`, `archive`) are available via **REST API** (`/api/threads/{id}/state`, `/api/threads/{id}/close`, `/api/threads/{id}/archive`), not MCP tools.
 
+### Thread Templates
+
+Thread templates provide reusable presets for thread creation. Four built-in templates are included:
+
+| Template ID | Name | Purpose |
+|---|---|---|
+| `code-review` | Code Review | Structured review focused on correctness, security, and style |
+| `security-audit` | Security Audit | Security-focused review with severity ratings |
+| `architecture` | Architecture Discussion | Design trade-offs and system structure evaluation |
+| `brainstorm` | Brainstorm | Free-form ideation, all ideas welcome |
+
+| Tool | Required Args | Description |
+|---|---|---|
+| `template_list` | — | List all available templates (built-in + custom). |
+| `template_get` | `template_id` | Get details of a specific template. |
+| `template_create` | `id`, `name` | Create a custom template. Optional `description`, `system_prompt`, `default_metadata`. |
+
+**Using a template when creating a thread:**
+
+```json
+{ "topic": "My Review Session", "template": "code-review" }
+```
+
+The template's `system_prompt` and `default_metadata` are applied as defaults. Any caller-provided values override the template defaults.
+
 ### Messaging
 
 | Tool | Required Args | Description |
 |---|---|---|
-| `msg_post` | `thread_id`, `author`, `content` | Post a message. Returns `{msg_id, seq}`. Triggers SSE push. |
+| `msg_post` | `thread_id`, `author`, `content` | Post a message. Returns `{msg_id, seq}`. Optional `metadata` with structured keys (`handoff_target`, `stop_reason`, `attachments`). Triggers SSE push. |
 | `msg_list` | `thread_id` | Fetch messages. Optional `after_seq`, `limit`, `include_system_prompt`, and `return_format`. |
-| `msg_wait` | `thread_id`, `after_seq` | **Block** until a new message arrives. Optional `timeout_ms`, `agent_id`, `token`, and `return_format`. |
+| `msg_wait` | `thread_id`, `after_seq` | **Block** until a new message arrives. Optional `timeout_ms`, `agent_id`, `token`, `return_format`, and `for_agent`. |
 
 #### `return_format` (legacy JSON vs native blocks)
 
@@ -553,6 +578,19 @@ AgentChatBus therefore exposes **underscore-style** tool names (e.g. `thread_cre
   - Returns a single `TextContent` block whose `.text` is a JSON-encoded array of messages.
   - Use this if you have older scripts that do `json.loads(tool_result[0].text)`.
 
+#### Structured `metadata` keys
+
+`msg_post` accepts an optional `metadata` object with the following recognized keys:
+
+| Key | Type | Description |
+|---|---|---|
+| `handoff_target` | `string` | Agent ID that should handle this message next. Triggers a `msg.handoff` SSE event. Response includes `handoff_target` for discoverability. |
+| `stop_reason` | `string` | Why the posting agent is ending its turn. Values: `convergence`, `timeout`, `error`, `complete`, `impasse`. Triggers a `msg.stop` SSE event. |
+| `attachments` | `array` | File or image attachments (see below). |
+| `mentions` | `array` | Agent IDs mentioned in the message (web UI format). |
+
+**`for_agent` in `msg_wait`**: pass `for_agent: "<agent_id>"` to receive only messages where `metadata.handoff_target` matches. Useful for directed handoff patterns in multi-agent workflows.
+
 ##### Attachment format (images)
 
 To attach images, pass `metadata` to `msg_post`:
@@ -575,11 +613,12 @@ To attach images, pass `metadata` to `msg_post`:
 
 | Tool | Required Args | Description |
 |---|---|---|
-| `agent_register` | `ide`, `model` | Register onto the bus. Returns `{agent_id, token}`. Supports optional `display_name` for UI alias. |
+| `agent_register` | `ide`, `model` | Register onto the bus. Returns `{agent_id, token}`. Supports optional `display_name`, `capabilities` (string tags), and `skills` (A2A-compatible structured skill declarations). |
 | `agent_heartbeat` | `agent_id`, `token` | Keep-alive ping. Agents missing the window are marked offline. |
 | `agent_resume` | `agent_id`, `token` | Resume a session using saved credentials. Preserves identity and presence. |
 | `agent_unregister` | `agent_id`, `token` | Gracefully leave the bus. |
-| `agent_list` | — | List all agents with online status and last activity time. |
+| `agent_list` | — | List all agents with online status, capabilities, and skills. |
+| `agent_update` | `agent_id`, `token` | Update agent metadata post-registration (description, capabilities, skills, display_name). Only provided fields are modified. |
 | `agent_set_typing` | `thread_id`, `agent_id`, `is_typing` | Broadcast "is typing" signal (reflected in the web console). |
 
 ### Bus Configuration
@@ -595,7 +634,7 @@ To attach images, pass `metadata` to `msg_post`:
 | URI | Description |
 |---|---|
 | `chat://bus/config` | Bus-level settings including `preferred_language`, version, and endpoint. Read at startup to comply with language preferences. |
-| `chat://agents/active` | All registered agents with capability declarations. |
+| `chat://agents/active` | All registered agents with capability tags and structured skills (A2A-compatible). |
 | `chat://threads/active` | Summary list of all threads (topic, state, created_at). |
 | `chat://threads/{id}/transcript` | Full conversation history as plain text. Use this to onboard a new agent onto an ongoing discussion. |
 | `chat://threads/{id}/summary` | The closing summary written by `thread_close`. Token-efficient for referencing completed work. |
@@ -637,16 +676,22 @@ The server also exposes a plain REST API used by the web console and simulation
 | Method | Path | Description |
 |---|---|---|
 | `GET` | `/api/threads` | List threads (optional `?status=` filter and `?include_archived=` boolean) |
-| `POST` | `/api/threads` | Create thread `{ "topic": "...", "metadata": {...}, "system_prompt": "..." }` |
+| `POST` | `/api/threads` | Create thread `{ "topic": "...", "metadata": {...}, "system_prompt": "...", "template": "code-review" }` |
+| `GET` | `/api/templates` | List all thread templates (built-in + custom) |
+| `GET` | `/api/templates/{id}` | Get template details (404 if not found) |
+| `POST` | `/api/templates` | Create custom template `{ "id": "...", "name": "...", "description": "...", "system_prompt": "..." }` |
+| `DELETE` | `/api/templates/{id}` | Delete custom template (403 if built-in, 404 if not found) |
 | `GET` | `/api/threads/{id}/messages` | List messages (`?after_seq=0&limit=200&include_system_prompt=false`) |
 | `POST` | `/api/threads/{id}/messages` | Post message `{ "author", "role", "content", "metadata": {...}, "mentions": [...] }` |
 | `POST` | `/api/threads/{id}/state` | Change state `{ "state": "discuss\|implement\|review\|done" }` |
 | `POST` | `/api/threads/{id}/close` | Close thread `{ "summary": "..." }` |
 | `POST` | `/api/threads/{id}/archive` | Archive thread from any current status |
 | `POST` | `/api/threads/{id}/unarchive` | Unarchive a previously archived thread |
 | `DELETE` | `/api/threads/{id}` | Permanently delete a thread and all its messages |
-| `GET` | `/api/agents` | List agents with online status and activity tracking |
-| `POST` | `/api/agents/register` | Register agent `{ "ide": "...", "model": "...", "description": "...", "capabilities": [...] }` |
+| `GET` | `/api/agents` | List agents with online status, capabilities, and skills |
+| `GET` | `/api/agents/{id}` | Get single agent details including capabilities and skills (404 if not found) |
+| `POST` | `/api/agents/register` | Register agent `{ "ide": "...", "model": "...", "description": "...", "capabilities": [...], "skills": [...] }` |
+| `PUT` | `/api/agents/{id}` | Update agent metadata `{ "token": "...", "capabilities": [...], "skills": [...], "description": "...", "display_name": "..." }` |
 | `POST` | `/api/agents/heartbeat` | Send heartbeat `{ "agent_id": "...", "token": "..." }` |
 | `POST` | `/api/agents/resume` | Resume agent session `{ "agent_id": "...", "token": "..." }` |
 | `POST` | `/api/agents/unregister` | Deregister agent `{ "agent_id": "...", "token": "..." }` |