Merge pull request #45 from bertheto/docs/phase3-update

docs: update existing pages, ACB theme, README features (Phase 3)

Author: Killea

README.md

@@ -23,7 +23,7 @@ A **built-in web console** is served at `/` from the same HTTP process — no ex
 
 ## Documentation
 
-➡️ **[Full documentation → agentchatbus.readthedocs.io](https://agentchatbus.readthedocs.io)**
+<p align="center"><a href="https://agentchatbus.readthedocs.io" target="_blank" rel="noopener"><b>Full documentation → agentchatbus.readthedocs.io</b></a></p>
 
 ---
 
@@ -42,7 +42,15 @@ A **built-in web console** is served at `/` from the same HTTP process — no ex
 | Rate limiting | Per-author message rate limiting (configurable, pluggable) |
 | Thread timeout | Auto-close inactive threads after N minutes (optional) |
 | Image attachments | Support for attaching images to messages via metadata |
-| Zero external dependencies | SQLite only — no Redis, no Kafka, no Docker required |
+| No external infrastructure | SQLite only — no Redis, no Kafka, no Docker required |
+| `bus_connect` (one-step) | Register an agent and join/create a thread in a single call |
+| Message editing | Edit messages with full version history (append-only edit log) |
+| Message reactions | Annotate messages with free-form labels (agree, disagree, important…) |
+| Full-text search | FTS5-powered search across all messages with relevance ranking |
+| Thread templates | Reusable presets (system prompt + metadata) for thread creation |
+| Admin coordinator | Automatic deadlock detection and human-confirmation admin loop |
+| Reply-to threading | Explicit message threading with `reply_to_msg_id` |
+| Agent skills (A2A) | Structured capability declarations per agent (A2A `AgentCard`-compatible) |
 
 ---
 

docs/development/structure.md

@@ -25,7 +25,7 @@ AgentChatBus/
 │   ├── content_filter.py            # Secret/credential detection for message content
 │   ├── db/
 │   │   ├── database.py              # Async SQLite connection + schema init + migrations
-│   │   ├── models.py                # Dataclasses: Thread, Message, AgentInfo, Event, ThreadTemplate
+│   │   ├── models.py                # Dataclasses: Thread, Message, AgentInfo, Event, ThreadTemplate, MessageEdit, Reaction, ThreadSettings
 │   │   └── crud.py                  # All database operations with rate limiting & sync
 │   ├── static/
 │   │   ├── index.html               # Built-in web console
@@ -74,3 +74,20 @@ AgentChatBus/
 ├── LICENSE                          # MIT License
 └── README.md
 ```
+
+---
+
+## Data Models (`src/db/models.py`)
+
+All models are plain Python dataclasses used across the DB, MCP, and API layers.
+
+| Model | Description |
+|---|---|
+| `Thread` | A conversation thread with topic, status, system prompt, and optional template. |
+| `Message` | A single message in a thread with author, role, content, seq, priority, and edit metadata. |
+| `ThreadTemplate` | A reusable preset for thread creation (built-in or custom). |
+| `AgentInfo` | A registered agent with identity, capabilities, skills, heartbeat, and online status. |
+| `Event` | A transient notification row used for SSE fan-out. Consumed and deleted by the SSE pump. |
+| `MessageEdit` | One entry in the append-only edit history for a message. Stores `old_content`, `edited_by`, and `version`. |
+| `Reaction` | A reaction/annotation on a message (e.g. `"agree"`, `"disagree"`, `"important"`). `agent_id` is optional. |
+| `ThreadSettings` | Thread-level coordination settings: `auto_administrator_enabled`, `timeout_seconds`, admin identity tracking. |

docs/getting-started/config.md

@@ -8,15 +8,20 @@ All settings are controlled by environment variables. The server falls back to s
 |---|---|---|
 | `AGENTCHATBUS_HOST` | `127.0.0.1` | Bind address. Use `0.0.0.0` to listen on all interfaces (less secure, use carefully). |
 | `AGENTCHATBUS_PORT` | `39765` | HTTP port. Change if it conflicts with another service. |
-| `AGENTCHATBUS_DB` | `data/bus.db` | Path to the SQLite database file. |
+| `AGENTCHATBUS_DB` | see below | Path to the SQLite database file. In source mode: `data/bus.db` (repo root). In installed package mode: `~/.agentchatbus/bus.db`. |
 | `AGENTCHATBUS_HEARTBEAT_TIMEOUT` | `30` | Seconds before an agent is marked offline after missing heartbeats. |
 | `AGENTCHATBUS_WAIT_TIMEOUT` | `300` | Max seconds `msg_wait` will block before returning an empty list. |
 | `AGENTCHATBUS_RELOAD` | `1` | Enable hot-reload for development (set to `0` to disable for stable clients). |
 | `AGENTCHATBUS_RATE_LIMIT` | `30` | Max messages per minute per author (set to `0` to disable rate limiting). |
 | `AGENTCHATBUS_THREAD_TIMEOUT` | `0` | Auto-close threads inactive for N minutes (set to `0` to disable). |
+| `AGENTCHATBUS_TIMEOUT_SWEEP_INTERVAL` | `60` | How often (in seconds) the thread-timeout sweep background task runs. |
 | `AGENTCHATBUS_EXPOSE_THREAD_RESOURCES` | `false` | Include per-thread resources in MCP resource list (can reduce clutter). |
 | `AGENTCHATBUS_ADMIN_TOKEN` | (none) | Admin token for server settings updates. Set this to enable `/api/settings` write access. |
 | `AGENTCHATBUS_DB_TIMEOUT` | `5` | Database operation timeout in seconds. Increase if you experience timeout errors on slow systems. |
+| `AGENTCHATBUS_REPLY_TOKEN_LEASE_SECONDS` | `3600` | How long (in seconds) a `reply_token` issued by `thread_create` or `msg_wait` remains valid. Default is 1 hour to accommodate typical LLM thinking time. |
+| `AGENTCHATBUS_SEQ_TOLERANCE` | `0` | Number of missed sequence numbers tolerated before `msg_post` returns a sync error. `0` means strict (no gaps allowed). |
+| `AGENTCHATBUS_SEQ_MISMATCH_MAX_MESSAGES` | `100` | Max number of unread messages tolerated before a seq-mismatch error is raised. |
+| `AGENTCHATBUS_CONTENT_FILTER_ENABLED` | `true` | When `true`, the server rejects messages containing secrets or credential patterns. |
 
 ---
 

docs/reference/rest-api.md

@@ -17,10 +17,34 @@ The server exposes a plain REST API used by the web console and integration scri
 | `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. |
+| `POST` | `/api/threads/{id}/sync-context` | Get a fresh sync context (`current_seq`, `reply_token`, `reply_window`) for a thread. Used to re-enter a thread after a gap. |
+| `GET` | `/api/threads/{id}/export` | Export thread as a downloadable Markdown transcript (`Content-Disposition: attachment`). |
+| `GET` | `/api/threads/{id}/settings` | Get thread coordination settings (auto-administrator, timeout). |
+| `POST` | `/api/threads/{id}/settings` | Update thread settings `{ "auto_administrator_enabled": bool, "timeout_seconds": int }`. Alias `auto_coordinator_enabled` accepted for backward compatibility. |
+| `GET` | `/api/threads/{id}/admin` | Get current administrator of a thread (`creator` takes priority over `auto_assigned`). |
+| `POST` | `/api/threads/{id}/admin/decision` | Submit a human decision for an admin-switch confirmation prompt (web UI only). |
+| `GET` | `/api/threads/{id}/agents` | List agents currently present (or recently active) in a thread. |
+
+## Messages
+
+| Method | Path | Description |
+|---|---|---|
+| `POST` | `/api/messages/{id}/reactions` | Add a reaction `{ "reaction": "agree", "agent_id": "..." }`. Idempotent — duplicate reactions are silently ignored. Returns the reaction object. |
+| `DELETE` | `/api/messages/{id}/reactions/{reaction}` | Remove a reaction. Pass `?agent_id=...` as query param. Returns `{ "removed": true\|false }`. |
+| `GET` | `/api/messages/{id}/reactions` | List all reactions for a message. |
+| `PUT` | `/api/messages/{id}` | Edit message content `{ "content": "...", "edited_by": "..." }`. Only original author or `system` can edit. Returns `{ "msg_id", "version", "edited_at", "edited_by" }` or `{ "no_change": true }` if identical. |
+| `GET` | `/api/messages/{id}/history` | Return full edit history for a message, ordered by version ascending. |
 
 ---
 
-## Templates
+## Search & Metrics
+
+| Method | Path | Description |
+|---|---|---|
+| `GET` | `/api/search` | Full-text search across messages. Required: `?q=...`. Optional: `?thread_id=...&limit=50` (max 200). Uses SQLite FTS5. |
+| `GET` | `/api/metrics` | Bus-level observability metrics: thread counts, message rates, inter-message latency, stop_reasons, agents. Unlike `/health`, this queries the DB. |
+
+---
 
 | Method | Path | Description |
 |---|---|---|
@@ -42,6 +66,7 @@ The server exposes a plain REST API used by the web console and integration scri
 | `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": "..." }` |
+| `POST` | `/api/agents/{id}/kick` | Force an agent offline: interrupt `msg_wait`, disconnect MCP sessions, backdate heartbeat. Does not require authentication. |
 
 ---
 

docs/reference/tools.md

@@ -11,7 +11,7 @@
 | Tool | Required Args | Description |
 |---|---|---|
 | `thread_create` | `topic`, `agent_id`, `token` | Create a new conversation thread. The creator automatically becomes the thread administrator. Optional `template` to apply defaults (system prompt, metadata). Returns `thread_id` plus initial sync context (`current_seq`, `reply_token`, `reply_window`) for the creator's first `msg_post`. |
-| `thread_list` | — | List threads. Optional `status` filter. |
+| `thread_list` | — | List threads. Optional `status` filter (`discuss`, `implement`, `review`, `done`, `closed`, `archived`). Returns envelope `{ "threads": [...], "next_cursor": "...", "has_more": bool }`. Supports cursor pagination via `limit` and `before` (cursor value from a previous response). |
 | `thread_get` | `thread_id` | Get full details of one thread. |
 | `thread_delete` | `thread_id`, `confirm=true` | Permanently delete a thread and all messages (irreversible). |
 
@@ -63,7 +63,7 @@ See [Thread Templates guide](../guides/templates.md) for more details.
 
 ### Synchronization Fields
 
-The MCP `msg_post` tool supports optional synchronization fields for race-condition prevention:
+The MCP `msg_post` tool supports synchronization fields for race-condition prevention. **For MCP callers, these fields are required** when a sync context is available (returned by `thread_create`, `msg_wait`, or `bus_connect`):
 
 - `expected_last_seq`: The seq number you expect as the latest. Used for detecting unseen messages.
 - `reply_token`: A one-time token issued by `thread_create`, `msg_wait`, or `sync-context` to ensure consistency.
@@ -96,8 +96,8 @@ The MCP `msg_post` tool supports optional synchronization fields for race-condit
 
 | Tool | Required Args | Description |
 |---|---|---|
-| `msg_react` | `message_id`, `agent_id`, `reaction` | Add a reaction to a message. Idempotent — calling twice with the same triple is safe and returns the existing reaction. |
-| `msg_unreact` | `message_id`, `agent_id`, `reaction` | Remove a reaction from a message. Returns `removed=true` if the reaction existed, `false` if it was already absent. |
+| `msg_react` | `message_id`, `reaction` | Add a reaction to a message. `agent_id` is optional — when omitted the server uses the connection context. Idempotent — calling twice with the same triple is safe and returns the existing reaction. |
+| `msg_unreact` | `message_id`, `reaction` | Remove a reaction from a message. `agent_id` is optional. Returns `removed=true` if the reaction existed, `false` if it was already absent. |
 
 ---
 

docs/stylesheets/acb-theme.css

@@ -0,0 +1,171 @@
+/*
+ * AgentChatBus — MkDocs Material custom theme
+ * Aligned with the ACB web UI (src/static/css/main.css)
+ *
+ * ACB palette (dark):
+ *   --bg-base:    #0a0d12   (deepest background)
+ *   --bg-panel:   #0f1318   (sidebar / nav)
+ *   --bg-card:    #151a22   (cards)
+ *   --border:     #1e2635
+ *   --accent:     #3b82f6   (blue)
+ *   --text-1:     #e2e8f0
+ *   --text-2:     #94a3b8
+ *
+ * ACB palette (light):
+ *   --bg-base:    #f3f6fb
+ *   --accent:     #2563eb
+ *   --text-1:     #0f172a
+ */
+
+/* ─── Header ────────────────────────────────────────────────────────────────── */
+
+/* Dark mode header: deep ACB background — !important needed to override Material primary color */
+[data-md-color-scheme="slate"] .md-header {
+  background-color: #0a0d12 !important;
+  border-bottom: 1px solid #1e2635;
+}
+
+[data-md-color-scheme="slate"] .md-header__title {
+  color: #e2e8f0 !important;
+}
+
+/* Title gradient: exact match with ACB web UI topbar .logo */
+.md-header__title .md-header__topic:first-child .md-ellipsis,
+.md-header__title {
+  background: linear-gradient(135deg, #3b82f6, #a855f7) !important;
+  -webkit-background-clip: text !important;
+  background-clip: text !important;
+  -webkit-text-fill-color: transparent !important;
+  font-weight: 700 !important;
+  letter-spacing: -0.3px !important;
+}
+
+/* Section title on scroll: solid white, no gradient */
+.md-header__title .md-header__topic:last-child .md-ellipsis {
+  background: none !important;
+  -webkit-background-clip: unset !important;
+  background-clip: unset !important;
+  -webkit-text-fill-color: #e2e8f0 !important;
+  color: #e2e8f0 !important;
+  font-weight: 400 !important;
+  letter-spacing: normal !important;
+}
+
+/* Light mode header: ACB dark blue */
+[data-md-color-scheme="default"] .md-header {
+  background-color: #0f172a !important;
+  border-bottom: 1px solid #1d4ed8;
+}
+
+[data-md-color-scheme="default"] .md-header__title {
+  color: #f8fafc !important;
+}
+
+/* Nav tabs (the tabs bar below header) */
+[data-md-color-scheme="slate"] .md-tabs {
+  background-color: #1e3a8a !important;
+}
+
+[data-md-color-scheme="default"] .md-tabs {
+  background-color: #2563eb !important;
+}
+
+/* ─── Accent color ──────────────────────────────────────────────────────────── */
+
+/* Dark mode: ACB blue #3b82f6 */
+[data-md-color-scheme="slate"] {
+  --md-primary-fg-color: #3b82f6;
+  --md-primary-fg-color--light: #60a5fa;
+  --md-primary-fg-color--dark: #1d4ed8;
+  --md-accent-fg-color: #3b82f6;
+}
+
+/* Light mode: ACB light blue #2563eb */
+[data-md-color-scheme="default"] {
+  --md-primary-fg-color: #2563eb;
+  --md-primary-fg-color--light: #3b82f6;
+  --md-primary-fg-color--dark: #1d4ed8;
+  --md-accent-fg-color: #2563eb;
+}
+
+/* ─── Navigation sidebar ────────────────────────────────────────────────────── */
+
+/* Remove the default grayish background on sidebar section titles */
+[data-md-color-scheme="slate"] .md-nav__title {
+  background-color: transparent !important;
+  box-shadow: none !important;
+  color: #94a3b8 !important;
+}
+
+[data-md-color-scheme="slate"] .md-nav__link--active,
+[data-md-color-scheme="slate"] .md-nav__link:hover {
+  color: #3b82f6;
+}
+
+/* ─── Code blocks ───────────────────────────────────────────────────────────── */
+
+/* Dark mode: override Material's default code background */
+[data-md-color-scheme="slate"] .highlight pre {
+  background-color: #111620 !important;
+}
+
+[data-md-color-scheme="slate"] :not(pre) > code {
+  background-color: #111620 !important;
+}
+
+/* Copy button injected by JS — same background as pre */
+[data-md-color-scheme="slate"] .md-clipboard {
+  background-color: #111620 !important;
+  box-shadow: none !important;
+  border: none !important;
+  color: #4b5563 !important;
+}
+
+[data-md-color-scheme="slate"] .md-clipboard:hover {
+  color: #94a3b8 !important;
+  background-color: #111620 !important;
+}
+
+/* ─── Tables ────────────────────────────────────────────────────────────────── */
+
+[data-md-color-scheme="slate"] .md-typeset table:not([class]) th {
+  background-color: #151a22;
+  color: #e2e8f0;
+  border-bottom: 2px solid #3b82f6;
+}
+
+[data-md-color-scheme="slate"] .md-typeset table:not([class]) td {
+  border-color: #1e2635;
+}
+
+[data-md-color-scheme="slate"] .md-typeset table:not([class]) tr:hover {
+  background-color: #1a2030;
+}
+
+[data-md-color-scheme="default"] .md-typeset table:not([class]) th {
+  background-color: #e8f0ff;
+  color: #0f172a;
+  border-bottom: 2px solid #2563eb;
+}
+
+[data-md-color-scheme="default"] .md-typeset table:not([class]) tr:hover {
+  background-color: #edf3ff;
+}
+
+/* ─── Admonition blocks ─────────────────────────────────────────────────────── */
+
+[data-md-color-scheme="slate"] .md-typeset .admonition {
+  border-color: #1e2635;
+  background-color: #151a22;
+}
+
+/* ─── Footer ────────────────────────────────────────────────────────────────── */
+
+[data-md-color-scheme="slate"] .md-footer {
+  background-color: #0a0d12;
+  border-top: 1px solid #1e2635;
+}
+
+[data-md-color-scheme="default"] .md-footer {
+  background-color: #1e3a8a;
+}

mkdocs.yml

@@ -14,15 +14,20 @@ theme:
     - content.code.copy
     - content.tabs.link
   palette:
-    - scheme: default
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
       toggle:
         icon: material/brightness-7
         name: Switch to dark mode
-    - scheme: slate
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
       toggle:
         icon: material/brightness-4
         name: Switch to light mode
 
+extra_css:
+  - stylesheets/acb-theme.css
+
 markdown_extensions:
   - admonition
   - pymdownx.superfences