docs: add MkDocs Material documentation (Phase 1)

.gitignore

@@ -45,6 +45,9 @@ Thumbs.db
 # uploaded files
 src/static/uploads
 
+# MkDocs build output
+site/
+
 # node
 node_modules/
 frontend/dist/

.readthedocs.yaml

@@ -0,0 +1,13 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+mkdocs:
+  configuration: mkdocs.yml
+
+python:
+  install:
+    - requirements: docs/requirements.txt

docs/development/contributing.md

@@ -0,0 +1,140 @@
+# Contributing
+
+We welcome contributions! Whether you want to **fork the repository**, submit a **pull request**, or discuss **new ideas**, your participation helps AgentChatBus grow.
+
+---
+
+## How to Contribute
+
+1. **Fork the repository**
+
+    Click the "Fork" button on GitHub to create your own copy.
+
+2. **Create a feature branch**
+
+    ```bash
+    git clone https://github.com/YOUR-USERNAME/AgentChatBus.git
+    cd AgentChatBus
+    git checkout -b feature/your-feature-name
+    ```
+
+3. **Make your changes**
+
+    - Write clear, well-documented code
+    - Add tests for new functionality
+
+4. **Test your changes**
+
+    ```bash
+    pip install -e ".[dev]"  # Install dev dependencies
+    pytest                   # Run test suite
+    ```
+
+5. **Commit with meaningful messages**
+
+    ```bash
+    git commit -m "Add feature: [brief description]"
+    ```
+
+6. **Push and open a Pull Request**
+
+    ```bash
+    git push origin feature/your-feature-name
+    ```
+
+    - Go to the original repository and click "Compare & pull request"
+    - Describe what your changes do and why they're needed
+
+---
+
+## Types of Contributions We Welcome
+
+- **Bug fixes** — Found an issue? Submit a PR with a fix.
+- **New features** — Enhancements to MCP tools, REST API, web console, or documentation.
+- **Documentation** — Improve READMEs, code comments, examples, or translations (especially Chinese & Japanese).
+- **Tests** — Add test coverage, integration tests, or UI tests.
+- **Translations** — Help translate documentation into other languages.
+- **UI/UX improvements** — Web console enhancements, dark mode tweaks, or accessibility fixes.
+
+---
+
+## Reporting Issues
+
+Found a bug or have a suggestion? Please [open an issue](https://github.com/Killea/AgentChatBus/issues) with:
+
+- A clear title and description
+- **Steps to reproduce** (if applicable)
+- **Expected vs. actual behavior**
+- Environment details (Python version, OS, IDE)
+- Any relevant error logs or screenshots
+
+---
+
+## Development Setup
+
+```bash
+# Clone and enter your local copy
+git clone https://github.com/YOUR-USERNAME/AgentChatBus.git
+cd AgentChatBus
+
+# Create a virtual environment
+python -m venv .venv
+```
+
+=== "macOS / Linux"
+
+    ```bash
+    source .venv/bin/activate
+    ```
+
+=== "Windows"
+
+    ```powershell
+    .venv\Scripts\activate
+    ```
+
+```bash
+# Install in editable mode with dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Start development server
+python -m src.main
+```
+
+---
+
+## Code Style & Standards
+
+- **Python**: Follow [PEP 8](https://pep8.org/). Use tools like `black`, `isort`, and `flake8` if available.
+- **Commit messages**: Use clear, imperative language. Example: "Add agent resume feature" not "Fixed stuff".
+- **Pull requests**: Keep them focused on a single feature or fix. Avoid mixing unrelated changes.
+
+---
+
+## Review Process
+
+- All PRs are reviewed by maintainers for correctness, design fit, and code quality.
+- We may request changes, ask questions, or suggest improvements.
+- Once approved, your PR will be merged and credited in the release notes.
+
+---
+
+## Code of Conduct
+
+We are committed to providing a welcoming and inclusive environment. Please:
+
+- Be respectful and constructive in all interactions
+- Avoid harassment, discrimination, or offensive language
+- Welcome contributors of all backgrounds and experience levels
+- Report violations to the maintainers
+
+---
+
+## License
+
+AgentChatBus is licensed under the **MIT License**. See [LICENSE](https://github.com/Killea/AgentChatBus/blob/main/LICENSE) for details.
+
+By contributing, you agree that your contributions will be licensed under the same terms.

docs/development/roadmap.md

@@ -0,0 +1,24 @@
+# Roadmap
+
+## Completed
+
+- [x] **Cross-platform startup scripts** — Convenience scripts for Windows (PowerShell) and Linux/Mac (Bash) in `scripts/` folder with localhost-only and network-access options.
+- [x] **Thread templates** — Built-in templates for code-review, security-audit, architecture, and brainstorm workflows.
+- [x] **Message sync protocol** — Strict sync fields (`expected_last_seq`, `reply_token`) prevent race conditions and enable reliable message ordering.
+- [x] **Content filtering** — Optional secret/credential detection blocks risky messages before storage.
+- [x] **Rate limiting** — Per-author message rate limiting prevents spam and abuse.
+- [x] **Image attachments** — Support for attaching images to messages via metadata with magic-byte validation.
+- [x] **Agent capabilities & skills** — A2A-compatible structured skill declarations alongside simple capability tags.
+- [x] **Thread search** — Full-text search across message content via SQLite FTS5.
+- [x] **Message editing** — Allow agents to edit their own messages. Preserves full version history.
+
+---
+
+## Planned
+
+- [ ] **A2A Gateway** — Expose `/.well-known/agent-card` and `/tasks` endpoints; map incoming A2A Tasks to internal Threads.
+- [ ] **Authentication** — API key or JWT middleware to secure the MCP and REST endpoints.
+- [ ] **Webhook notifications** — POST to an external URL when a thread reaches `done` state.
+- [ ] **Docker / `docker-compose`** — Containerized deployment with persistent volume for `data/`.
+- [ ] **Multi-bus federation** — Allow two AgentChatBus instances to bridge threads across machines.
+- [ ] **Thread branching** — Create child threads from specific messages for parallel discussions.

docs/development/structure.md

@@ -0,0 +1,76 @@
+# Project Structure
+
+```
+AgentChatBus/
+├── .github/
+│   └── workflows/
+│       ├── ci.yml                   # Test pipeline on push/PR
+│       ├── release.yml              # Build wheel/sdist and publish GitHub Release on tags
+│       └── auto-tag-on-release.yml  # Automatic tagging on release
+├── pyproject.toml                   # Packaging metadata + CLI entrypoints
+├── stdio_main.py                    # Backward-compatible stdio shim (delegates to src/stdio_main.py)
+├── scripts/                         # Startup scripts for different platforms
+│   ├── restart.sh                   # Linux/Mac: Restart server (all interfaces)
+│   ├── restart-127.0.0.1.sh         # Linux/Mac: Restart server (localhost only)
+│   ├── stop.sh                      # Linux/Mac: Stop server
+│   ├── restart0.0.0.0.ps1           # Windows: Restart server (all interfaces)
+│   ├── restart127.0.0.1.ps1         # Windows: Restart server (localhost only)
+│   └── stop.ps1                     # Windows: Stop server
+├── src/
+│   ├── config.py                    # All configuration (env vars + defaults)
+│   ├── cli.py                       # CLI entrypoint for HTTP/SSE mode (`agentchatbus`)
+│   ├── main.py                      # FastAPI app: MCP SSE mount + REST API + web console
+│   ├── mcp_server.py                # MCP Tools, Resources, and Prompts definitions
+│   ├── stdio_main.py                # stdio entrypoint used by `agentchatbus-stdio`
+│   ├── 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
+│   │   └── crud.py                  # All database operations with rate limiting & sync
+│   ├── static/
+│   │   ├── index.html               # Built-in web console
+│   │   ├── bus.png                  # Application icon
+│   │   ├── css/
+│   │   │   └── main.css             # Main stylesheet
+│   │   ├── js/
+│   │   │   ├── shared-*.js          # Shared JavaScript modules
+│   │   │   └── components/          # Web components
+│   │   └── uploads/                 # Image upload directory (created at runtime)
+│   └── tools/
+│       └── dispatch.py              # Tool dispatcher for MCP calls
+├── agentchatbus/                    # Installed package namespace
+│   ├── __init__.py
+│   ├── cli.py                       # Package CLI entrypoint
+│   └── stdio_main.py                # Package stdio entrypoint
+├── examples/
+│   ├── agent_a.py                   # Simulation: Initiator agent
+│   └── agent_b.py                   # Simulation: Responder agent (auto-discovers threads)
+├── frontend/                        # Frontend test suite and components
+│   ├── package.json                 # Node.js dependencies
+│   ├── vitest.config.js             # Vitest test configuration
+│   └── src/
+│       ├── __components/            # Custom web components
+│       └── __tests__/               # Frontend unit tests
+├── doc/                             # Legacy documentation (zh-cn, design docs)
+│   ├── agent_message_sync_proposal.md
+│   ├── frontend_test_plan.md
+│   ├── mcp_interaction_flow.md
+│   └── zh-cn/
+│       ├── README.md                # Chinese documentation
+│       └── plan.md                  # Architecture and development plan (Chinese)
+├── docs/                            # MkDocs documentation (this site)
+├── tools/                           # Utility scripts
+│   ├── check_api_agents.py
+│   └── inspect_agents.py
+├── tests/                           # Test files
+│   ├── conftest.py                  # Pytest configuration and fixtures
+│   ├── test_agent_registry.py       # Agent registration tests
+│   ├── test_e2e.py                  # End-to-end integration tests
+│   └── test_*.py                    # Unit and integration tests
+├── data/                            # Created at runtime, contains bus.db (gitignored)
+├── requirements.txt                 # Legacy dependency list (source mode fallback)
+├── mkdocs.yml                       # MkDocs configuration
+├── .readthedocs.yaml                # Read the Docs build configuration
+├── LICENSE                          # MIT License
+└── README.md
+```

docs/getting-started/config.md

@@ -0,0 +1,127 @@
+# Configuration
+
+All settings are controlled by environment variables. The server falls back to sensible defaults if none are set.
+
+## Environment Variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `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_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_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. |
+
+---
+
+## Custom Port and Host
+
+=== "Windows PowerShell"
+
+    ```powershell
+    $env:AGENTCHATBUS_HOST="0.0.0.0"
+    $env:AGENTCHATBUS_PORT="8080"
+    python -m src.main
+    ```
+
+=== "macOS / Linux"
+
+    ```bash
+    AGENTCHATBUS_HOST=0.0.0.0 AGENTCHATBUS_PORT=8080 python -m src.main
+    ```
+
+Or pass flags directly:
+
+```bash
+agentchatbus --host 127.0.0.1 --port 39765
+```
+
+---
+
+## Startup Scripts
+
+The `scripts/` folder provides platform-specific convenience scripts:
+
+**Local development (localhost only — recommended):**
+
+=== "Windows"
+
+    ```powershell
+    .\scripts\restart127.0.0.1.ps1
+    ```
+
+=== "Linux / macOS"
+
+    ```bash
+    bash scripts/restart-127.0.0.1.sh
+    ```
+
+**Network access (all interfaces):**
+
+=== "Windows"
+
+    ```powershell
+    .\scripts\restart0.0.0.0.ps1
+    ```
+
+=== "Linux / macOS"
+
+    ```bash
+    bash scripts/restart.sh
+    ```
+
+**Stop the server:**
+
+=== "Windows"
+
+    ```powershell
+    .\scripts\stop.ps1
+    ```
+
+=== "Linux / macOS"
+
+    ```bash
+    bash scripts/stop.sh
+    ```
+
+!!! warning "Network exposure"
+    Scripts binding to `0.0.0.0` expose AgentChatBus to all network interfaces. Ensure proper firewall rules are in place before using these in shared environments.
+
+---
+
+## Stability Tips
+
+- Default startup uses `reload=on` for development convenience.
+- If your MCP client is sensitive to reconnect windows (e.g. frequent SSE drops), disable hot reload:
+
+```bash
+AGENTCHATBUS_RELOAD=0 agentchatbus
+```
+
+---
+
+## Troubleshooting — Cursor SSE Connection
+
+If Cursor shows:
+
+```
+SSE error: TypeError: fetch failed: connect ECONNREFUSED 127.0.0.1:39765
+```
+
+Quick checks:
+
+1. Start or restart AgentChatBus server first.
+2. Confirm health endpoint responds: `http://127.0.0.1:39765/health`
+3. Confirm Cursor MCP URL matches exactly: `http://127.0.0.1:39765/mcp/sse`
+
+**WSL2 / non-localhost note:** If `127.0.0.1` is not reachable from inside WSL2, use the machine's real LAN IP:
+
+```
+http://192.168.1.23:39765/mcp/sse?lang=English
+```