ARIA
b1c9bac7d8
- docs/install.md: new end-to-end guide for non-technical users (gateway install, app install, LAN/TLS/remote connection, push, options, troubleshooting); docs/setup.md now points to it - README: new 'Install the gateway' section; pairing section updated for HTTP transport (8791, QR scan on Android) - rename IRIS_WS_HOST -> IRIS_HTTP_HOST (clean rename, no compat fallback); drop dead DEFAULT_PORT=8790 - setup.py: advertise https:// in the printed/QR server URL when IRIS_HTTP_CERT is set - ws_probe.py/e2e.py: default --url http://127.0.0.1:8791, env IRIS_WS_URL -> IRIS_HTTP_URL, honor explicit port + https scheme - plugin.yaml: IRIS_HTTP_* env names, description no longer says 'WebSocket server' - docs 03/09/12/19: fix stale WS-era refs (ws_server.py cites, 8790 smoke test, WSS->HTTPS, 'HTTP fallback' reframed as the only transport) - AGENTS.md: symlink name android -> iris (matches actual install) - test: adapter reads IRIS_HTTP_HOST/CERT/KEY from env; legacy IRIS_WS_* names are not consulted (95/95 pass)
79 lines
4.3 KiB
Markdown
79 lines
4.3 KiB
Markdown
# Iris × Hermes — Implementation Reference Library
|
||
|
||
A coder-facing reference library for building a **native Android + Desktop
|
||
experience** for [hermes-agent](https://github.com/NousResearch/hermes-agent),
|
||
connected through a **gateway platform plugin**.
|
||
|
||
This folder is the single source of truth for *what to build and why*. Read it
|
||
top-to-bottom once, then use the numbered docs as a lookup while implementing.
|
||
|
||
> ⚠️ **READ FIRST — two hard rules**
|
||
>
|
||
> 1. **`hermes-agent/` (sibling of this folder) is a read-only research
|
||
> reference. It must NEVER be committed, pushed, or shipped.** It is
|
||
> git-ignored at the repo root. We only *install* our plugin into a live
|
||
> hermes install (`~/.hermes/plugins/`); we never modify hermes core.
|
||
> 2. **ADB is installed and a device is connected** (`a5ca2a4b`, Xiaomi MIX 2S,
|
||
> Android 10 / API 29). Use it to install/launch/debug the app on-device.
|
||
|
||
---
|
||
|
||
## User-facing guides
|
||
|
||
- [`install.md`](install.md) — **install the gateway + connect the app** (non-technical walkthrough, all options, TLS, push).
|
||
- [`setup.md`](setup.md) — moved; pointer to `install.md`.
|
||
|
||
## Reading order
|
||
|
||
| # | File | When to read |
|
||
| --- | ------ | -------------- |
|
||
| 0 | [`00-overview.md`](00-overview.md) | Always first. Vision, scope, disclaimers, locked decisions. |
|
||
| 1 | [`01-architecture.md`](01-architecture.md) | Before touching code. System shape + rationale. |
|
||
| 2 | [`02-monorepo.md`](02-monorepo.md) | When scaffolding the repo. |
|
||
| 3 | [`03-gateway-plugin.md`](03-gateway-plugin.md) | When building the Python plugin. |
|
||
| 4 | [`04-wire-protocol.md`](04-wire-protocol.md) | When implementing either side of the WS. |
|
||
| 5 | [`05-streaming.md`](05-streaming.md) | Streaming / reasoning / tools / intermediate. |
|
||
| 6 | [`06-channels-cron-search.md`](06-channels-cron-search.md) | Channels, threads, cron delivery, search. |
|
||
| 7 | [`07-media.md`](07-media.md) | Media upload/download + playback. |
|
||
| 8 | [`08-push.md`](08-push.md) | Push (ntfy default + FCM optional), outbox, sync. |
|
||
| 9 | [`09-pairing-security.md`](09-pairing-security.md) | Pairing, auth, security model. |
|
||
| 10 | [`10-android-app.md`](10-android-app.md) | When building the Iris app (Android). |
|
||
| 11 | [`11-desktop-app.md`](11-desktop-app.md) | When building the Desktop app. |
|
||
| 12 | [`12-toolchain.md`](12-toolchain.md) | First time on a machine (JDK/SDK/uv/Firebase). |
|
||
| 13 | [`13-testing.md`](13-testing.md) | Writing tests + on-device ADB workflow. |
|
||
| 14 | [`14-milestones.md`](14-milestones.md) | Planning work / tracking progress. |
|
||
| 15 | [`15-hermes-reference.md`](15-hermes-reference.md) | **Cheat-sheet** of hermes-agent source to read. |
|
||
| 16 | [`16-open-questions.md`](16-open-questions.md) | Decisions made + open items. |
|
||
| 17 | [`17-future-control-surface.md`](17-future-control-surface.md) | **Backlog** — what the app could control beyond chat (cron, kanban, models, …). |
|
||
| 19 | [`19-http-fallback-transport.md`](19-http-fallback-transport.md) | **Design** — HTTP fallback leg (POST + SSE/long-poll) so the app can send/receive when the WS is down. |
|
||
| 20 | [`20-qr-pairing.md`](20-qr-pairing.md) | Terminal QR at `gateway setup` + in-app QR scanner (Android) + `iris://pair` deep link. |
|
||
|
||
Machine-readable / diagrams:
|
||
|
||
- [`protocol/frames.schema.json`](protocol/frames.schema.json) — wire-frame schema.
|
||
- [`diagrams/architecture.mmd`](diagrams/architecture.mmd) — mermaid architecture.
|
||
- [`playstore-listing.md`](playstore-listing.md) — Play Store listing text (incl. the FCM/ntfy privacy note).
|
||
|
||
---
|
||
|
||
## The three deliverables (one monorepo)
|
||
|
||
1. **`gateway-plugin/`** — a Python hermes **platform plugin** named `iris`.
|
||
Runs inside the `hermes gateway` process. Opens a WebSocket server the apps
|
||
connect to. Implements the full `BasePlatformAdapter` contract. **Zero new
|
||
Python dependencies, zero hermes-core changes.**
|
||
2. **`app/androidApp`** — native Kotlin + Jetpack Compose client.
|
||
3. **`app/desktopApp`** — Kotlin + Compose Multiplatform client that *shares*
|
||
the Iris app's code and is "tweaked" for a big screen.
|
||
|
||
The Iris Android and Desktop clients live in **one Compose Multiplatform Gradle
|
||
project** (`app/`) with a shared KMP module (`app/shared`).
|
||
|
||
---
|
||
|
||
## Status
|
||
|
||
- **Phase:** M0–M6 complete; M7 (polish + E2E + docs) in progress.
|
||
- **Owner decisions locked:** see [`16-open-questions.md`](16-open-questions.md).
|
||
- **Last updated:** 2026-08-19.
|