docs: document Matrix appservice integration and gitea deployment

- Add Matrix bot to the feature list and prerequisites.
- Add a Matrix Appservice section covering config, Synapse registration,
  and the shared conversation pipeline.
- Document the matrix config section in CONFIGURATION.md.
- Add a ready-to-use Synapse appservice registration template
  (matrix/steward_appservice.yaml).
- Document the Gitea Actions build/deploy workflow and kube manifests.

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>

CONFIGURATION.md

@@ -199,6 +199,36 @@ tools:
 - `STEWARD__TOOLS__MCP_SERVER_URL`
 - `STEWARD__TOOLS__MCP_SERVER_API_KEY`
 
+### Matrix Section
+
+```yaml
+matrix:
+  homeserver_url: ""               # Homeserver client-server base URL (e.g. http://matrix:8008)
+  homeserver_domain: ""            # Homeserver server_name (e.g. matrix.aridgwayweb.com)
+  as_token: ""                     # Appservice token (authenticates to the homeserver)
+  hs_token: ""                     # Homeserver token (authenticates incoming transactions)
+  bot_localpart: "steward"         # Bot user localpart -> @steward:<domain>
+  appservice_id: "steward"         # Unique appservice ID
+  listen_host: "0.0.0.0"           # Appservice HTTP server host
+  listen_port: 8000                # Appservice HTTP server port
+  allowed_room_ids: []             # Room allow-list (empty = all rooms)
+  allowed_user_ids: []             # User MXID allow-list (empty = all users)
+```
+
+**Environment Variables:**
+- `STEWARD__MATRIX__HOMESERVER_URL`
+- `STEWARD__MATRIX__HOMESERVER_DOMAIN`
+- `STEWARD__MATRIX__AS_TOKEN`
+- `STEWARD__MATRIX__HS_TOKEN`
+- `STEWARD__MATRIX__BOT_LOCALPART`
+- `STEWARD__MATRIX__APPSERVICE_ID`
+- `STEWARD__MATRIX__LISTEN_HOST`
+- `STEWARD__MATRIX__LISTEN_PORT`
+- `STEWARD__MATRIX__ALLOWED_ROOM_IDS` - Comma-separated list of room IDs
+- `STEWARD__MATRIX__ALLOWED_USER_IDS` - Comma-separated list of user MXIDs
+
+The Matrix bot is enabled when `homeserver_url`, `as_token`, and `hs_token` are all set. See [`matrix/steward_appservice.yaml`](matrix/steward_appservice.yaml) for the Synapse appservice registration template.
+
 ## Environment Variable Format
 
 Environment variables follow the pattern: `STEWARD__SECTION__KEY=value`

README.md

@@ -5,6 +5,7 @@ Steward is a long-running, AI-assisted personal operations platform designed to
 ## Features
 
 - **Telegram Bot**: Group/channel support with thread-based conversations
+- **Matrix Bot**: Native Matrix application-service (appservice) integration via Synapse
 - **Message Threads**: Organized conversations with automatic summarization
 - **Knowledge Base**: Stores and retrieves conversation summaries
 - **LLM Integration**: OpenAI-compatible API support
@@ -17,8 +18,9 @@ Steward is a long-running, AI-assisted personal operations platform designed to
 
 - Python 3.12+
 - Docker & Docker Compose
-- Telegram Bot Token (from [@BotFather](https://t.me/botfather))
+- Telegram Bot Token (from [@BotFather](https://t.me/botfather)) — required for the Telegram bot
 - OpenAI API Key
+- A Matrix homeserver (e.g. Synapse) — required for the Matrix appservice bot
 
 ### Local Development
 
@@ -48,6 +50,24 @@ docker compose -f docker-compose.dev.yml up --build
 
 See [CONFIGURATION.md](CONFIGURATION.md) for detailed configuration options.
 
+### Matrix Appservice
+
+Steward can run as a native Matrix bot by registering it as a Synapse application service. When configured, it receives room events via HTTP transactions and replies through the client-server API, reusing the same conversation pipeline as the Telegram bot.
+
+To enable it:
+
+1. Configure the `matrix` section (via `STEWARD__MATRIX__*` env vars or a config file):
+   - `homeserver_url` — the homeserver client-server base URL (e.g. `http://matrix:8008`)
+   - `homeserver_domain` — the server name (e.g. `matrix.aridgwayweb.com`)
+   - `as_token` / `hs_token` — the appservice tokens
+   - `bot_localpart` — the bot user localpart (defaults to `steward`)
+   - `listen_host` / `listen_port` — where the appservice HTTP server listens
+   - `allowed_room_ids` / `allowed_user_ids` — optional allow-lists
+
+2. Register the appservice with Synapse. See [`matrix/steward_appservice.yaml`](matrix/steward_appservice.yaml) for a ready-to-use registration template, and add it to your `homeserver.yaml` under `app_service_config_files:`.
+
+3. Start Steward. It will run the Telegram bot, the Matrix appservice, or both depending on which are configured.
+
 ### Running Tests
 
 ```bash
@@ -86,6 +106,8 @@ On every commit. You can skip with `git commit --no-verify` if needed.
 
 For Kubernetes deployment, see examples in [CONFIGURATION.md](CONFIGURATION.md#kubernetes).
 
+The repo includes a Gitea Actions workflow (`.gitea/workflows/build_push.yml`) that builds a multi-arch Docker image, pushes it to the gitea registry, and deploys to Kubernetes using the manifests in [`kube/`](kube/). The deployment uses a NodePort service exposing port 30002 (the Matrix appservice endpoint) and a persistent volume for thread memory.
+
 Production image: `ghcr.io/djw4/steward:latest`
 
 ## License

matrix/steward_appservice.yaml

@@ -0,0 +1,29 @@
+# Steward Matrix appservice registration for Synapse.
+#
+# Copy this to the Synapse config dir (e.g. /config/steward.yaml) and add to
+# homeserver.yaml:
+#
+#   app_service_config_files:
+#     - /config/steward.yaml
+#
+# Then restart Synapse. The appservice bot user @steward:matrix.aridgwayweb.com
+# is created automatically from sender_localpart; no register_new_matrix_user
+# step is needed.
+#
+# The `url` must be reachable from Synapse. In-cluster this is the Steward
+# appservice NodePort (30002) or an in-cluster service URL.
+
+id: "steward"
+url: "http://<steward-appservice-host>:30002"
+as_token: "<AS_TOKEN>"
+hs_token: "<HS_TOKEN>"
+sender_localpart: "steward"
+rate_limited: false
+namespaces:
+  users:
+    - exclusive: false
+      regex: "@steward:matrix\\.aridgwayweb\\.com"
+  aliases:
+    - exclusive: false
+      regex: "#steward.*:matrix\\.aridgwayweb\\.com"
+  rooms: []