feat: matrix-hermes project structure and Matrix authentication

README.md

@@ -0,0 +1,57 @@
+# Matrix-Hermes
+
+Matrix authentication and client integration for Hermes Agent.
+
+## Overview
+
+`matrix-hermes` provides authentication, client connectivity, and bridge
+utilities for integrating Hermes Agent with the Matrix protocol.  Works
+with any Matrix homeserver (self-hosted or matrix.org).
+
+## Features
+
+- **Authentication**: Login with password or access token, device registration
+- **Client**: Async Matrix client wrapping mautrix SDK
+- **CLI**: Command-line tools for authentication setup and token management
+- **Config**: `.env`-based configuration compatible with Hermes gateway
+
+## Quick Start
+
+```bash
+pip install -e .
+matrix-hermes login --homeserver https://matrix.org --user @bot:matrix.org
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `MATRIX_HOMESERVER` | Homeserver URL |
+| `MATRIX_ACCESS_TOKEN` | Access token (preferred) |
+| `MATRIX_USER_ID` | Full user ID (@user:server) |
+| `MATRIX_PASSWORD` | Password (alternative auth) |
+| `MATRIX_DEVICE_ID` | Stable device ID for E2EE |
+| `MATRIX_ENCRYPTION` | Enable E2EE (true/false) |
+
+## Project Structure
+
+```
+matrix-hermes/
+├── pyproject.toml
+├── README.md
+├── src/
+│   └── matrix_hermes/
+│       ├── __init__.py
+│       ├── auth.py       # Login, token, device management
+│       ├── client.py     # Async Matrix client wrapper
+│       ├── config.py     # Configuration from env/file
+│       └── cli.py        # CLI entry point
+└── tests/
+    ├── conftest.py
+    ├── test_auth.py
+    └── test_client.py
+```
+
+## License
+
+MIT