abstractgateway 0.1.0__tar.gz → 0.1.1__tar.gz

abstractgateway-0.1.1/ACKNOWLEDGMENTS.md

@@ -0,0 +1,30 @@
+# Acknowledgments
+
+AbstractGateway stands on the shoulders of many open-source projects and contributors.
+
+This list is **non-exhaustive**. The canonical dependency list for this package is in `pyproject.toml`.
+
+## Core dependencies
+
+- **AbstractRuntime**: durable run model, workflow registry, file/SQLite stores, and runtime tick loop.
+- **FastAPI** (via **Starlette**) + **Pydantic**: HTTP API surface and request/response models.
+- **Uvicorn**: ASGI server used by `abstractgateway serve`.
+
+## Optional integrations (feature-dependent)
+
+These are not required for the base gateway, but are used by optional modes/features:
+
+- **AbstractFlow**: VisualFlow JSON directory mode and workflow authoring/bundling workflows (see `abstractgateway[visualflow]`).
+- **AbstractCore** integration (via `abstractruntime[abstractcore]`): LLM/tool execution wiring, embeddings client, Telegram TDLib wrapper.
+- **AbstractAgent**: Visual Agent nodes in bundle mode.
+- **AbstractMemory** + **LanceDB**: `memory_kg_*` nodes in bundle mode (knowledge graph storage).
+- **TDLib**: Telegram Secret Chats support when using the TDLib transport.
+
+## Dev/test tooling
+
+- **pytest** and **httpx**: test suite and HTTP client utilities used under `tests/`.
+- **hatchling**: Python packaging/build backend.
+
+## Contributors
+
+Thank you to everyone who reports issues, improves documentation, and contributes code.

abstractgateway-0.1.1/ACKNOWLEDMENTS.md

@@ -0,0 +1,6 @@
+# ACKNOWLEDMENTS
+
+This file exists for compatibility.
+
+See: [ACKNOWLEDGMENTS.md](./ACKNOWLEDGMENTS.md)
+

abstractgateway-0.1.1/CHANGELOD.md

@@ -0,0 +1,6 @@
+# CHANGELOD
+
+This file exists for compatibility.
+
+See: [CHANGELOG.md](./CHANGELOG.md)
+

abstractgateway-0.1.1/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.1] - 2026-02-04
+
+### Changed
+
+- Documentation refresh for external users:
+  - new FAQ (`docs/faq.md`)
+  - clarified quickstart + smoke checks in `README.md`
+  - tightened getting started, configuration, security, and API overview docs
+  - improved cross-linking in `CONTRIBUTING.md` and `SECURITY.md`
+  - refreshed `llms.txt` / `llms-full.txt` for agent ingestion (index + full snapshot)
+- Version bump to reflect the documentation release (`0.1.0` → `0.1.1`).
+
+### Notes
+
+- No intentional runtime behavior changes in this release; it is documentation-focused.
+
+## [0.1.0] - 2026-02-03
+
+### Added
+
+- Initial public package for AbstractGateway (`abstractgateway`).

abstractgateway-0.1.1/CONTRIBUTING.md

@@ -0,0 +1,63 @@
+# Contributing
+
+Thanks for your interest in improving AbstractGateway.
+
+This repo is a Python package (`src/` layout) with a FastAPI server, a durable runner worker, and contract tests under `tests/`.
+
+## Quick start (dev)
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+
+python -m pip install -U pip
+pip install -e ".[dev,http]"
+```
+
+Run the test suite:
+
+```bash
+pytest
+```
+
+If you only want the fast/unit/contract layer:
+
+```bash
+pytest -m basic
+```
+
+Notes:
+- `integration` and `e2e` tests may require optional dependencies and/or external services (e.g. an LLM provider).
+- The CLI entrypoint is `abstractgateway` (see `pyproject.toml`).
+
+## How to contribute
+
+1. **Open an issue** (or a draft PR) describing what you want to change and why.
+2. Keep changes **small and reviewable**.
+3. Add/adjust tests where it improves confidence.
+4. Update docs so they remain truthful and user-facing:
+   - README is the entrypoint.
+   - `docs/getting-started.md` is the step-by-step guide.
+   - Prefer adding FAQ entries for recurring “gotchas”.
+
+## Project conventions
+
+- Source of truth is the code in `src/`.
+- Keep public docs concise, actionable, and aligned with the current behavior.
+- Prefer explicit env var names as used in code (see `docs/configuration.md`).
+
+## Release checklist (maintainers)
+
+1. Update `CHANGELOG.md`.
+2. Bump version in:
+   - `pyproject.toml`
+   - `src/abstractgateway/__init__.py`
+   - `src/abstractgateway/app.py` (FastAPI version string)
+3. Run `pytest`.
+4. Build artifacts (optional): `python -m build`
+
+## Related docs
+
+- Package overview + quickstart: [README.md](./README.md)
+- Docs index: [docs/README.md](./docs/README.md)
+- Getting started: [docs/getting-started.md](./docs/getting-started.md)

abstractgateway-0.1.1/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: abstractgateway
+Version: 0.1.1
+Summary: AbstractGateway: deployable Run Gateway host for AbstractRuntime (commands + ledger).
+Project-URL: GitHub, https://github.com/lpalbou/abstractgateway
+Author: Laurent-Philippe Albou
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: abstractruntime>=0.4.0
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.100.0; extra == 'dev'
+Requires-Dist: httpx>=0.27.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: uvicorn[standard]>=0.23.0; extra == 'dev'
+Provides-Extra: http
+Requires-Dist: fastapi>=0.100.0; extra == 'http'
+Requires-Dist: uvicorn[standard]>=0.23.0; extra == 'http'
+Provides-Extra: runner
+Provides-Extra: telegram
+Requires-Dist: abstractruntime[abstractcore]>=0.4.0; extra == 'telegram'
+Provides-Extra: visualflow
+Requires-Dist: abstractflow>=0.3.0; extra == 'visualflow'
+Description-Content-Type: text/markdown
+
+# AbstractGateway
+
+AbstractGateway is a **deployable Run Gateway host** for AbstractRuntime runs:
+- start durable runs
+- accept a durable command inbox
+- replay/stream a durable ledger (replay-first)
+- enforce a security baseline (token + origin allowlist + limits)
+
+This decouples the gateway service from any specific UI (AbstractFlow, AbstractCode, web/PWA thin clients).
+
+Start here: [docs/getting-started.md](docs/getting-started.md)
+
+## Quickstart (HTTP server, bundle mode)
+
+```bash
+pip install "abstractgateway[http]"
+
+export ABSTRACTGATEWAY_FLOWS_DIR="/path/to/bundles"   # *.flow dir (or a single .flow file)
+export ABSTRACTGATEWAY_DATA_DIR="$PWD/runtime/gateway"
+
+# Required by default: the server refuses to start without a token.
+export ABSTRACTGATEWAY_AUTH_TOKEN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
+# Browser-origin allowlist (glob patterns). Default allows localhost; customize when exposing remotely.
+export ABSTRACTGATEWAY_ALLOWED_ORIGINS="http://localhost:*,http://127.0.0.1:*"
+
+abstractgateway serve --host 127.0.0.1 --port 8080
+```
+
+OpenAPI docs (Swagger UI): `http://127.0.0.1:8080/docs`
+
+Smoke checks:
+
+```bash
+curl -sS "http://127.0.0.1:8080/api/health"
+
+curl -sS -H "Authorization: Bearer $ABSTRACTGATEWAY_AUTH_TOKEN" \
+  "http://127.0.0.1:8080/api/gateway/bundles"
+```
+
+## Client contract (replay-first)
+
+- Clients **start runs**: `POST /api/gateway/runs/start`
+- Clients **act** by submitting durable commands: `POST /api/gateway/commands`
+  - supported types: `pause|resume|cancel|emit_event|update_schedule|compact_memory`
+- Clients **render** by replaying/streaming the durable ledger:
+  - replay: `GET /api/gateway/runs/{run_id}/ledger?after=...`
+  - stream (SSE): `GET /api/gateway/runs/{run_id}/ledger/stream?after=...`
+
+See [docs/api.md](docs/api.md) for curl examples and the live OpenAPI spec (`/openapi.json`).
+
+## Install
+
+### Base (runner + stores + CLI)
+
+Requires Python `>=3.10` (see `pyproject.toml`).
+
+```bash
+pip install abstractgateway
+```
+
+### HTTP API/SSE server (FastAPI + Uvicorn)
+
+```bash
+pip install "abstractgateway[http]"
+```
+
+### Optional extras
+
+- `abstractgateway[visualflow]`: run VisualFlow JSON from a directory of `*.json` files (requires `abstractflow`)
+- `abstractgateway[telegram]`: Telegram bridge dependencies
+- `abstractgateway[dev]`: local test/dev deps
+
+### Bundle-dependent dependencies (only if your workflows need them)
+
+- LLM/tool nodes in bundle mode require AbstractRuntime’s AbstractCore integration:
+
+```bash
+pip install "abstractruntime[abstractcore]>=0.4.0"
+```
+
+For details on `ABSTRACTGATEWAY_PROVIDER`/`MODEL`, store backends, and workflow sources, see [docs/configuration.md](docs/configuration.md).
+
+## Creating a `.flow` bundle (authoring)
+
+Use AbstractFlow to pack a bundle:
+
+```bash
+abstractflow bundle pack /path/to/root.json --out /path/to/bundles/my.flow --flows-dir /path/to/flows
+```
+
+See [docs/getting-started.md](docs/getting-started.md) for running, split API/runner, and file→SQLite migration.
+
+## Docs
+
+### Project docs
+
+- Changelog: [CHANGELOG.md](CHANGELOG.md) (compat: `CHANGELOD.md`)
+- Contributing: [CONTRIBUTING.md](CONTRIBUTING.md)
+- Security policy (vulnerability reporting): [SECURITY.md](SECURITY.md)
+- Acknowledgments: [ACKNOWLEDGMENTS.md](ACKNOWLEDGMENTS.md) (compat: `ACKNOWLEDMENTS.md`)
+
+### Package docs
+
+- Docs index: [docs/README.md](docs/README.md)
+- Getting started: [docs/getting-started.md](docs/getting-started.md)
+- FAQ: [docs/faq.md](docs/faq.md)
+- Architecture: [docs/architecture.md](docs/architecture.md)
+- Configuration: [docs/configuration.md](docs/configuration.md)
+- API overview: [docs/api.md](docs/api.md)
+- Security: [docs/security.md](docs/security.md)
+- Operator tooling (optional): [docs/maintenance.md](docs/maintenance.md)

abstractgateway-0.1.1/README.md

@@ -0,0 +1,111 @@
+# AbstractGateway
+
+AbstractGateway is a **deployable Run Gateway host** for AbstractRuntime runs:
+- start durable runs
+- accept a durable command inbox
+- replay/stream a durable ledger (replay-first)
+- enforce a security baseline (token + origin allowlist + limits)
+
+This decouples the gateway service from any specific UI (AbstractFlow, AbstractCode, web/PWA thin clients).
+
+Start here: [docs/getting-started.md](docs/getting-started.md)
+
+## Quickstart (HTTP server, bundle mode)
+
+```bash
+pip install "abstractgateway[http]"
+
+export ABSTRACTGATEWAY_FLOWS_DIR="/path/to/bundles"   # *.flow dir (or a single .flow file)
+export ABSTRACTGATEWAY_DATA_DIR="$PWD/runtime/gateway"
+
+# Required by default: the server refuses to start without a token.
+export ABSTRACTGATEWAY_AUTH_TOKEN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
+# Browser-origin allowlist (glob patterns). Default allows localhost; customize when exposing remotely.
+export ABSTRACTGATEWAY_ALLOWED_ORIGINS="http://localhost:*,http://127.0.0.1:*"
+
+abstractgateway serve --host 127.0.0.1 --port 8080
+```
+
+OpenAPI docs (Swagger UI): `http://127.0.0.1:8080/docs`
+
+Smoke checks:
+
+```bash
+curl -sS "http://127.0.0.1:8080/api/health"
+
+curl -sS -H "Authorization: Bearer $ABSTRACTGATEWAY_AUTH_TOKEN" \
+  "http://127.0.0.1:8080/api/gateway/bundles"
+```
+
+## Client contract (replay-first)
+
+- Clients **start runs**: `POST /api/gateway/runs/start`
+- Clients **act** by submitting durable commands: `POST /api/gateway/commands`
+  - supported types: `pause|resume|cancel|emit_event|update_schedule|compact_memory`
+- Clients **render** by replaying/streaming the durable ledger:
+  - replay: `GET /api/gateway/runs/{run_id}/ledger?after=...`
+  - stream (SSE): `GET /api/gateway/runs/{run_id}/ledger/stream?after=...`
+
+See [docs/api.md](docs/api.md) for curl examples and the live OpenAPI spec (`/openapi.json`).
+
+## Install
+
+### Base (runner + stores + CLI)
+
+Requires Python `>=3.10` (see `pyproject.toml`).
+
+```bash
+pip install abstractgateway
+```
+
+### HTTP API/SSE server (FastAPI + Uvicorn)
+
+```bash
+pip install "abstractgateway[http]"
+```
+
+### Optional extras
+
+- `abstractgateway[visualflow]`: run VisualFlow JSON from a directory of `*.json` files (requires `abstractflow`)
+- `abstractgateway[telegram]`: Telegram bridge dependencies
+- `abstractgateway[dev]`: local test/dev deps
+
+### Bundle-dependent dependencies (only if your workflows need them)
+
+- LLM/tool nodes in bundle mode require AbstractRuntime’s AbstractCore integration:
+
+```bash
+pip install "abstractruntime[abstractcore]>=0.4.0"
+```
+
+For details on `ABSTRACTGATEWAY_PROVIDER`/`MODEL`, store backends, and workflow sources, see [docs/configuration.md](docs/configuration.md).
+
+## Creating a `.flow` bundle (authoring)
+
+Use AbstractFlow to pack a bundle:
+
+```bash
+abstractflow bundle pack /path/to/root.json --out /path/to/bundles/my.flow --flows-dir /path/to/flows
+```
+
+See [docs/getting-started.md](docs/getting-started.md) for running, split API/runner, and file→SQLite migration.
+
+## Docs
+
+### Project docs
+
+- Changelog: [CHANGELOG.md](CHANGELOG.md) (compat: `CHANGELOD.md`)
+- Contributing: [CONTRIBUTING.md](CONTRIBUTING.md)
+- Security policy (vulnerability reporting): [SECURITY.md](SECURITY.md)
+- Acknowledgments: [ACKNOWLEDGMENTS.md](ACKNOWLEDGMENTS.md) (compat: `ACKNOWLEDMENTS.md`)
+
+### Package docs
+
+- Docs index: [docs/README.md](docs/README.md)
+- Getting started: [docs/getting-started.md](docs/getting-started.md)
+- FAQ: [docs/faq.md](docs/faq.md)
+- Architecture: [docs/architecture.md](docs/architecture.md)
+- Configuration: [docs/configuration.md](docs/configuration.md)
+- API overview: [docs/api.md](docs/api.md)
+- Security: [docs/security.md](docs/security.md)
+- Operator tooling (optional): [docs/maintenance.md](docs/maintenance.md)

abstractgateway-0.1.1/SECURITY.md

@@ -0,0 +1,36 @@
+# Security policy
+
+Thanks for helping keep AbstractGateway and its users safe.
+
+## Reporting a vulnerability
+
+Please **do not** open a public GitHub issue for security vulnerabilities.
+
+Instead, use GitHub’s **private vulnerability reporting** / **Security Advisories** for this repository:
+- Go to the repository’s **Security** tab
+- Open **Advisories**
+- Click **Report a vulnerability** (or create a draft advisory)
+
+If you cannot use GitHub advisories, contact the maintainers privately (e.g. via GitHub profile contact links).
+
+## What to include
+
+To help us triage quickly, include:
+- a clear description of the issue and impact
+- minimal reproduction steps or a PoC
+- affected versions and environments (OS/Python version/config)
+- any suggested mitigation or patch
+
+## Coordinated disclosure
+
+We appreciate responsible disclosure and will work with you to:
+- confirm the issue
+- assess severity and affected versions
+- produce a fix and release
+
+Please avoid active exploitation, privacy violations, or destructive testing.
+
+## Related docs
+
+- Security configuration (auth/origin/limits): [docs/security.md](./docs/security.md)
+- Getting started: [docs/getting-started.md](./docs/getting-started.md)

abstractgateway-0.1.1/docs/README.md

@@ -0,0 +1,28 @@
+# AbstractGateway docs
+
+Start here if you’re new to the project.
+
+## Docs map
+
+- Quickstart + stores (file/SQLite): [getting-started.md](./getting-started.md)
+- FAQ / troubleshooting: [faq.md](./faq.md)
+- Architecture (durable contract + components): [architecture.md](./architecture.md)
+- Configuration (env vars + install extras): [configuration.md](./configuration.md)
+- API overview (client contract + OpenAPI): [api.md](./api.md)
+- Security guide (auth/origin/limits/audit log): [security.md](./security.md)
+- Operator tooling (triage/backlog/process manager): [maintenance.md](./maintenance.md)
+
+## API docs (generated)
+
+When the HTTP server is running (`abstractgateway serve`):
+- Health: `GET /api/health`
+- OpenAPI JSON: `GET /openapi.json`
+- Interactive Swagger UI: `GET /docs`
+
+## Project docs
+
+- Package README: [../README.md](../README.md)
+- Changelog: [../CHANGELOG.md](../CHANGELOG.md) (compat: `CHANGELOD.md`)
+- Contributing: [../CONTRIBUTING.md](../CONTRIBUTING.md)
+- Security policy (vulnerability reporting): [../SECURITY.md](../SECURITY.md)
+- Acknowledgments: [../ACKNOWLEDGMENTS.md](../ACKNOWLEDGMENTS.md) (compat: `ACKNOWLEDMENTS.md`)

abstractgateway-0.1.1/docs/api.md

@@ -0,0 +1,175 @@
+# AbstractGateway — API overview
+
+The HTTP API is implemented with FastAPI under the `/api` prefix:
+- Health: `GET /api/health`
+- Gateway surface: `/api/gateway/*` (durable runs + operator tooling)
+
+The API is documented at runtime:
+- OpenAPI JSON: `GET /openapi.json`
+- Swagger UI: `GET /docs`
+
+## Auth
+
+By default, `/api/gateway/*` is protected by `GatewaySecurityMiddleware` (bearer token + origin allowlist).  
+See: [security.md](./security.md).
+
+All examples below assume:
+
+```bash
+export BASE_URL="http://127.0.0.1:8080"
+export AUTH="Authorization: Bearer $ABSTRACTGATEWAY_AUTH_TOKEN"
+```
+
+## Core workflow lifecycle
+
+### 1) List bundles (bundle mode)
+
+```bash
+curl -sS -H "$AUTH" "$BASE_URL/api/gateway/bundles"
+```
+
+Upload a bundle:
+
+```bash
+curl -sS -H "$AUTH" \
+  -F "file=@./my-bundle@0.1.0.flow" \
+  -F "overwrite=false" \
+  -F "reload=true" \
+  "$BASE_URL/api/gateway/bundles/upload"
+```
+
+### 2) Start a run
+
+```bash
+curl -sS -H "$AUTH" -H "Content-Type: application/json" \
+  -d '{"bundle_id":"my-bundle","input_data":{"prompt":"Hello"}}' \
+  "$BASE_URL/api/gateway/runs/start"
+```
+
+If you need a specific entrypoint:
+
+```bash
+curl -sS -H "$AUTH" -H "Content-Type: application/json" \
+  -d '{"bundle_id":"my-bundle","flow_id":"ac-echo","input_data":{"prompt":"Hello"}}' \
+  "$BASE_URL/api/gateway/runs/start"
+```
+
+Evidence: request/response models live in `src/abstractgateway/routes/gateway.py` (`StartRunRequest`, `start_run`).
+
+### 3) Replay the ledger (cursor-based)
+
+Ledger pages are replayed using `after` as “number of items already consumed”.
+
+```bash
+curl -sS -H "$AUTH" "$BASE_URL/api/gateway/runs/<run_id>/ledger?after=0&limit=200"
+```
+
+Response shape:
+- `items`: list of durable ledger records
+- `next_after`: the next cursor to use
+
+Evidence: `src/abstractgateway/routes/gateway.py` (`get_ledger`).
+
+### 4) Stream ledger updates (SSE)
+
+SSE is an optimization; clients should always be able to reconnect by replaying from the last `next_after`.
+
+```bash
+curl -N -H "$AUTH" "$BASE_URL/api/gateway/runs/<run_id>/ledger/stream?after=0"
+```
+
+Evidence: `src/abstractgateway/routes/gateway.py` (`stream_ledger`).
+
+## Durable commands (`POST /api/gateway/commands`)
+
+Commands are appended to a durable inbox and applied asynchronously by the runner.
+
+Request fields (see `SubmitCommandRequest` in `src/abstractgateway/routes/gateway.py`):
+- `command_id`: client-supplied idempotency key (UUID recommended)
+- `run_id`: target run id (or session id for some event use-cases)
+- `type`: `pause|resume|cancel|emit_event|update_schedule|compact_memory`
+- `payload`: command-specific object
+
+### Pause / cancel
+
+```bash
+curl -sS -H "$AUTH" -H "Content-Type: application/json" \
+  -d '{"command_id":"'"$(python -c 'import uuid; print(uuid.uuid4())')"'", "run_id":"<run_id>", "type":"pause", "payload":{"reason":"operator_pause"}}' \
+  "$BASE_URL/api/gateway/commands"
+```
+
+### Resume a paused run
+
+```bash
+curl -sS -H "$AUTH" -H "Content-Type: application/json" \
+  -d '{"command_id":"'"$(python -c 'import uuid; print(uuid.uuid4())')"'", "run_id":"<run_id>", "type":"resume", "payload":{}}' \
+  "$BASE_URL/api/gateway/commands"
+```
+
+### Resume a WAITING run with a payload (WAIT resume)
+
+When `payload.payload` is present, the runner interprets this as “resume a WAITING run with a durable payload”:
+
+```bash
+curl -sS -H "$AUTH" -H "Content-Type: application/json" \
+  -d '{"command_id":"'"$(python -c 'import uuid; print(uuid.uuid4())')"'", "run_id":"<run_id>", "type":"resume", "payload":{"wait_key":"<optional_wait_key>", "payload":{"approved":true}}}' \
+  "$BASE_URL/api/gateway/commands"
+```
+
+Evidence: `src/abstractgateway/runner.py` (`_apply_command`, `_apply_run_control`).
+
+### Emit an external event
+
+Minimal form:
+
+```bash
+curl -sS -H "$AUTH" -H "Content-Type: application/json" \
+  -d '{"command_id":"'"$(python -c 'import uuid; print(uuid.uuid4())')"'", "run_id":"<session_id>", "type":"emit_event", "payload":{"name":"chat.message","payload":{"text":"hi"}}}' \
+  "$BASE_URL/api/gateway/commands"
+```
+
+Evidence: `src/abstractgateway/runner.py` (`_apply_emit_event`).
+
+## Beyond the core
+
+`/api/gateway/*` also includes optional operator/tooling endpoints (reports inbox, triage queue, backlog browsing + exec runner, process manager, file/attachment helpers, embeddings, voice, discovery, …).  
+See: [maintenance.md](./maintenance.md).
+
+## Email inbox (operator UI; optional)
+
+These endpoints power AbstractObserver’s **Inbox → Email** UI. They are **account-scoped**: the browser cannot supply arbitrary IMAP/SMTP host/user credentials. The gateway host must be configured with one or more email accounts (multi-account YAML or env vars).
+
+Endpoints:
+- `GET /api/gateway/email/accounts`
+- `GET /api/gateway/email/messages?account=…&mailbox=…&since=…&status=…&limit=…`
+- `GET /api/gateway/email/messages/{uid}?account=…&mailbox=…&max_body_chars=…`
+- `POST /api/gateway/email/send`
+
+Examples:
+
+```bash
+curl -sS -H "$AUTH" "$BASE_URL/api/gateway/email/accounts"
+```
+
+```bash
+curl -sS -H "$AUTH" "$BASE_URL/api/gateway/email/messages?status=unread&since=7d&limit=20"
+```
+
+```bash
+curl -sS -H "$AUTH" "$BASE_URL/api/gateway/email/messages/12345?max_body_chars=20000"
+```
+
+```bash
+curl -sS -H "$AUTH" -H "Content-Type: application/json" \
+  -d '{"to":"you@example.com","subject":"Hello","body_text":"Hi!"}' \
+  "$BASE_URL/api/gateway/email/send"
+```
+
+Configuration notes (gateway host):
+- Multi-account: set `ABSTRACT_EMAIL_ACCOUNTS_CONFIG=/path/to/emails.yaml` (recommended).
+- Single-account env fallback: set `ABSTRACT_EMAIL_IMAP_*` and/or `ABSTRACT_EMAIL_SMTP_*`.
+- The secret itself must be present in the env var referenced by `*_PASSWORD_ENV_VAR` (e.g. `EMAIL_PASSWORD=...`).
+
+Evidence: `src/abstractgateway/routes/gateway.py` (`/email/accounts|messages|send`) which proxies to `abstractcore.tools.comms_tools`.
+
+Troubleshooting and common questions: [faq.md](./faq.md).