better-dsh 0.2.4 → 0.2.5-a

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/messaging/google_chat.md

@@ -0,0 +1,430 @@
+---
+sidebar_position: 12
+title: "Google Chat"
+description: "Set up Hermes Agent as a Google Chat bot using Cloud Pub/Sub"
+---
+
+# Google Chat Setup
+
+Connect Hermes Agent to Google Chat as a bot. The integration uses Cloud Pub/Sub
+pull subscriptions for inbound events and the Chat REST API for outbound messages.
+Equivalent ergonomics to Slack Socket Mode or Telegram long-polling: your Hermes
+process does not need a public URL, a tunnel, or a TLS certificate. It connects,
+authenticates, and listens on a subscription — the same way a Telegram bot listens
+on a token.
+
+> Run `hermes gateway setup` and pick **Google Chat** for a guided walk-through.
+
+:::note Workspace edition
+Google Chat is part of Google Workspace. You can use this integration with a
+personal Workspace (`@yourdomain.com` registered through Google) or a work
+Workspace where you have the Admin rights to publish an app. Gmail-only accounts
+cannot host Chat apps.
+:::
+
+## Overview
+
+| Component | Value |
+|-----------|-------|
+| **Libraries** | `google-cloud-pubsub`, `google-api-python-client`, `google-auth` |
+| **Inbound transport** | Cloud Pub/Sub pull subscription (no public endpoint) |
+| **Outbound transport** | Chat REST API (`chat.googleapis.com`) |
+| **Authentication** | Service Account JSON with `roles/pubsub.subscriber` on the subscription |
+| **User identification** | Chat resource names (`users/{id}`) + email |
+
+---
+
+## Step 1: Create or pick a GCP project
+
+You need a Google Cloud project to host the Pub/Sub topic. If you don't have one,
+create it at [console.cloud.google.com](https://console.cloud.google.com) —
+personal accounts get a free tier that easily covers bot traffic.
+
+Note the project ID (e.g., `my-chat-bot-123`). You'll use it in every subsequent
+step.
+
+---
+
+## Step 2: Enable two APIs
+
+In the console, go to **APIs & Services → Library** and enable:
+
+- **Google Chat API**
+- **Cloud Pub/Sub API**
+
+Both are free for the volumes a personal bot generates.
+
+---
+
+## Step 3: Create a Service Account
+
+**IAM & Admin → Service Accounts → Create Service Account.**
+
+- Name: `hermes-chat-bot`
+- Skip the "Grant this service account access to project" step. IAM on the specific
+  subscription is all you need — do **NOT** grant project-level Pub/Sub roles.
+
+After creation, open the SA, go to **Keys → Add Key → Create new key → JSON** and
+download the file. Save it somewhere only Hermes can read (e.g.,
+`~/.hermes/google-chat-sa.json`, `chmod 600`).
+
+:::caution There is NO "Chat Bot Caller" role
+A common mistake is to search for a Chat-specific IAM role and grant it at the
+project level. That role doesn't exist. Chat bot authority comes from being
+installed in a space, not from IAM. All your SA needs is Pub/Sub subscriber on
+the subscription you create in the next step.
+:::
+
+---
+
+## Step 4: Create the Pub/Sub topic and subscription
+
+**Pub/Sub → Topics → Create topic.**
+
+- Topic ID: `hermes-chat-events`
+- Leave the defaults for everything else.
+
+After creation, the topic's detail page has a **Subscriptions** tab. Create one:
+
+- Subscription ID: `hermes-chat-events-sub`
+- Delivery type: **Pull**
+- Message retention: **7 days** (so backlog survives a hermes restart)
+- Leave the rest default.
+
+---
+
+## Step 5: IAM binding on the topic (critical)
+
+On the **topic** (not the subscription), add an IAM principal:
+
+- Principal: `chat-api-push@system.gserviceaccount.com`
+- Role: `Pub/Sub Publisher`
+
+Without this, Google Chat cannot publish events to your topic and your bot will
+never receive anything.
+
+---
+
+## Step 6: IAM binding on the subscription
+
+On the **subscription**, add your own Service Account as a principal:
+
+- Principal: `hermes-chat-bot@<your-project>.iam.gserviceaccount.com`
+- Role: `Pub/Sub Subscriber`
+
+Also grant `Pub/Sub Viewer` on the same subscription — Hermes calls
+`subscription.get()` at startup as a reachability check.
+
+---
+
+## Step 7: Configure the Chat app
+
+Go to **APIs & Services → Google Chat API → Configuration**.
+
+- **App name**: whatever you want users to see ("Hermes" is reasonable).
+- **Avatar URL**: any public PNG (Google has some defaults).
+- **Description**: a short sentence shown in the app directory.
+- **Functionality**: enable **Receive 1:1 messages** and **Join spaces and group
+  conversations**.
+- **Connection settings**: select **Cloud Pub/Sub**, enter the topic name
+  `projects/<your-project>/topics/hermes-chat-events`.
+- **Visibility**: restrict to your workspace (or specific users) — do not publish
+  to everyone while you're testing.
+
+Save.
+
+---
+
+## Step 8: Install the bot in a test space
+
+Open Google Chat in a browser. Start a DM with your app by searching for its name
+in the **+ New Chat** menu. The first time you message it, Google sends an
+`ADDED_TO_SPACE` event that Hermes uses to cache the bot's own `users/{id}` for
+self-message filtering.
+
+---
+
+## Step 9: Configure Hermes
+
+Add the Google Chat section to `~/.hermes/.env`:
+
+```bash
+# Required
+GOOGLE_CHAT_PROJECT_ID=my-chat-bot-123
+GOOGLE_CHAT_SUBSCRIPTION_NAME=projects/my-chat-bot-123/subscriptions/hermes-chat-events-sub
+GOOGLE_CHAT_SERVICE_ACCOUNT_JSON=/home/you/.hermes/google-chat-sa.json
+
+# Authorization — paste the emails of people allowed to talk to the bot
+GOOGLE_CHAT_ALLOWED_USERS=you@yourdomain.com,coworker@yourdomain.com
+
+# Optional
+GOOGLE_CHAT_HOME_CHANNEL=spaces/AAAA...         # default delivery destination for cron jobs
+GOOGLE_CHAT_MAX_MESSAGES=1                      # Pub/Sub FlowControl; 1 serializes commands per session
+GOOGLE_CHAT_MAX_BYTES=16777216                  # 16 MiB — cap on in-flight message bytes
+```
+
+The project ID also falls back to `GOOGLE_CLOUD_PROJECT`, and the SA path falls
+back to `GOOGLE_APPLICATION_CREDENTIALS` — use whichever convention you prefer.
+
+Under a [multi-profile gateway](../multi-profile-gateways.md), every
+`GOOGLE_CHAT_*` setting is read from the routed profile's own `.env`; a
+secondary profile never inherits the default profile's project, subscription,
+or service account. If a profile has no SA configured while the process
+environment carries one for another profile, the adapter refuses to fall back
+to Application Default Credentials (which would authenticate as that other
+profile) and logs an explicit error instead — put
+`GOOGLE_CHAT_SERVICE_ACCOUNT_JSON` in that profile's `.env`.
+
+Install the Google Chat adapter dependencies through its maintained installer.
+It applies the same pinned security floors used by the runtime checks:
+
+```bash
+python -m plugins.platforms.google_chat.oauth --install-deps
+```
+
+On Docker / hosted images `/opt/hermes/.venv` is read-only. That installer
+routes through `tools.lazy_deps` into `HERMES_LAZY_INSTALL_TARGET`
+(`/opt/data/lazy-packages` in the official image) instead of writing
+site-packages. Restart the gateway after it finishes. The published image
+also bakes the `[google-chat]` extra so a fresh container does not need a
+first-boot install.
+
+Start the gateway:
+
+```bash
+hermes gateway
+```
+
+You should see a log line like:
+
+```
+[GoogleChat] Connected; project=my-chat-bot-123, subscription=<redacted>,
+             bot_user_id=users/XXXX, flow_control(msgs=1, bytes=16777216)
+```
+
+Send "hola" in the test DM. The bot posts a "Hermes is thinking…" marker, then
+edits that same message in place with the real response — no "message deleted"
+tombstones.
+
+### Customizing the working-state marker
+
+The marker text is configurable via `typing_status_text` in
+`~/.hermes/config.yaml` — e.g. a kitten assistant named Ada:
+
+```yaml
+platforms:
+  google_chat:
+    # Custom working-state marker text (default: "Hermes is thinking…").
+    typing_status_text: "is pouncing… 🐾"
+```
+
+Unlike Slack's ephemeral status line, this is a **real posted message** that
+gets edited in place with the response — so whatever you set here briefly
+appears in the chat as a normal message. Set `typing_indicator: false` to
+disable the marker entirely.
+
+---
+
+## Formatting and capabilities
+
+Google Chat renders a limited markdown subset:
+
+| Supported | Not supported |
+|-----------|---------------|
+| `*bold*`, `_italic_`, `~strike~`, `` `code` `` | Headings, lists |
+| Inline images via URL | Interactive Card v2 buttons (v1 of this gateway) |
+| Native file attachments (after `/setup-files` — see Step 10) | Native voice notes / circular video notes |
+
+The agent's system prompt includes a Google Chat–specific hint so it knows these
+limits and avoids formatting that won't render.
+
+Message size limit: 4000 characters per message. Longer agent responses are
+automatically split across multiple messages.
+
+Thread support: when a user replies inside a thread, Hermes detects the
+`thread.name` and posts its reply in the same thread, so each thread gets a
+separate Hermes session.
+
+### Clarify questions as interactive cards
+
+When the agent asks a multiple-choice clarify question, the adapter renders it
+as a native **Card v2** with one button per choice plus an
+**"Other / type answer"** button, instead of a plain numbered text list.
+Clicking a button answers the question directly (`CARD_CLICKED` events route
+the choice back into the waiting session). If the card fails to send, or the
+question has no fixed choices, the adapter falls back to the standard text
+clarify. No configuration needed.
+
+---
+
+## Step 10: Native attachment delivery (optional)
+
+Out of the box the bot can post text, inline images via URL, and download cards
+for audio/video/documents. To deliver **native** Chat attachments — the same
+file widget you get when a human drags-and-drops a file — each user authorizes
+the bot once via a per-user OAuth flow.
+
+### Why a separate flow
+
+Google Chat's `media.upload` endpoint hard-rejects service-account auth:
+
+> This method doesn't support app authentication with a service account.
+> Authenticate with a user account.
+
+There's no IAM role or scope that fixes this. The endpoint only accepts user
+credentials. So the bot has to act *as a user* whenever it uploads a file —
+specifically, as the user who asked for the file.
+
+### One-time setup (per profile)
+
+1. Go to **APIs & Services → Credentials** in the same GCP project.
+2. **Create credentials → OAuth client ID → Desktop app**.
+3. Download the JSON. Move it onto the host that runs Hermes.
+4. Register the client with Hermes (run under the profile you want it scoped to):
+
+```bash
+# Default profile:
+python -m plugins.platforms.google_chat.oauth \
+    --client-secret /path/to/client_secret.json
+
+# A named profile gets its own separate registration:
+hermes -p <profile> python -m plugins.platforms.google_chat.oauth \
+    --client-secret /path/to/client_secret.json
+```
+
+That writes the client secret into the active profile's Hermes home (e.g.
+`~/.hermes/google_chat_user_client_secret.json` for the default profile). The
+client secret is **profile-scoped, not shared across profiles** — each profile
+registers its own. This is deliberate: profiles are isolated auth boundaries, so
+two profiles can point at different Google OAuth apps / accounts. Register it
+once per profile that needs Google Chat attachment delivery.
+
+### Per-user authorization (in chat)
+
+Each user runs the flow once, in their own DM with the bot:
+
+1. They send `/setup-files` to the bot. It replies with status and the next
+   step.
+2. They send `/setup-files start`. The bot replies with an OAuth URL.
+3. They open the URL, click **Allow**, and watch the browser fail to load
+   `http://localhost:1/?...&code=...`. That failure is expected — the auth
+   code is in the URL bar.
+4. They copy the failed URL (or just the `code=...` value) and paste it back
+   into chat as `/setup-files <PASTED_URL>`. The bot exchanges it for a
+   refresh token.
+
+The token lands at `~/.hermes/google_chat_user_tokens/<sanitized_email>.json`.
+Subsequent file requests in that user's DM use *their* token, so the bot
+uploads as them and the message lands in their space.
+
+To revoke later: `/setup-files revoke` deletes only that user's token. Other
+users' tokens are untouched.
+
+### Scope
+
+The flow requests exactly one scope: `chat.messages.create`. That covers both
+`media.upload` and the `messages.create` that references the uploaded
+`attachmentDataRef`. No Drive, no broader Chat scopes — this is least-privilege
+on purpose.
+
+### Multi-user behavior
+
+When the asker has no per-user token yet, the bot falls back to a legacy
+single-user token at `~/.hermes/google_chat_user_token.json` (if present from
+a pre-multi-user install). When neither is available, the bot posts a clear
+text notice telling the asker to run `/setup-files`.
+
+A user revoking only clears their own slot. A 401/403 from one user's token
+evicts only that user's cache. Users don't disrupt each other.
+
+---
+
+## Troubleshooting
+
+**Bot stays silent after sending "hola."**
+
+1. Check the Pub/Sub subscription has undelivered messages in the console.
+   If it does, Hermes isn't authenticated — verify `GOOGLE_CHAT_SERVICE_ACCOUNT_JSON`
+   and that the SA is listed as `Pub/Sub Subscriber` on the subscription.
+2. If the subscription has zero messages, Google Chat isn't publishing.
+   Double-check the IAM binding on the **topic**:
+   `chat-api-push@system.gserviceaccount.com` must have `Pub/Sub Publisher`.
+3. Check `hermes gateway` logs for `[GoogleChat] Connected`. If you see
+   `[GoogleChat] Config validation failed`, the error message tells you which
+   env var to fix.
+
+**Bot replies but an error message appears instead of the agent's answer.**
+
+Check logs for `[GoogleChat] Pub/Sub stream died` — if these repeat, your SA
+credentials may have been rotated or the subscription deleted. After 10 attempts
+the adapter marks itself fatal.
+
+**"403 Forbidden" on every outbound message.**
+
+The bot was removed from the space, or you revoked it in the Chat API console.
+Re-install it in the space (the next `ADDED_TO_SPACE` event will re-enable
+messaging automatically).
+
+**Too many "Rate limit hit" warnings.**
+
+The Chat API's default quotas allow 60 messages per space per minute. If your
+agent produces long streaming responses that exceed that, the adapter retries
+with exponential backoff — but you'll still see user-visible latency. Consider
+concise responses or raising the quota in the GCP console.
+
+**Bot keeps posting the "/setup-files" notice instead of files.**
+
+The asker has no per-user OAuth token and there's no legacy fallback. Run
+`/setup-files` in their DM and follow Step 10. After the exchange completes
+the next file request uploads natively without a gateway restart.
+
+**`/setup-files start` says "No client credentials stored."**
+
+The one-time setup wasn't done *for this profile* (the client secret is
+profile-scoped, so a registration under one profile won't be seen by another).
+From a terminal, run it under the profile the gateway uses:
+
+```bash
+# Default profile:
+python -m plugins.platforms.google_chat.oauth \
+    --client-secret /path/to/client_secret.json
+
+# Named profile:
+hermes -p <profile> python -m plugins.platforms.google_chat.oauth \
+    --client-secret /path/to/client_secret.json
+```
+
+Then send `/setup-files start` again.
+
+**`/setup-files <PASTED_URL>` says "Token exchange failed."**
+
+The auth code is single-use and short-lived (typically a few minutes). Send
+`/setup-files start` to get a fresh URL and retry.
+
+---
+
+## Security notes
+
+- **Service Account scope**: the adapter requests `chat.bot` and `pubsub` scopes.
+  IAM should be the actual enforcement — grant your SA the minimum
+  (`roles/pubsub.subscriber` + `roles/pubsub.viewer` on the subscription), not
+  project-level or org-level Pub/Sub roles.
+- **Attachment download protection**: Hermes will only attach the SA bearer
+  token to URLs whose host matches a short allowlist of Google-owned domains
+  (`googleapis.com`, `drive.google.com`, `lh[3-6].googleusercontent.com`, and
+  a few others). Any other host is rejected before the HTTP request, to
+  protect against SSRF scenarios where a crafted event could redirect the
+  bearer token to the GCE metadata service.
+- **Redaction**: Service Account emails, subscription paths, and topic paths
+  are stripped from log output by `agent/redact.py`. The debug envelope dump
+  (`GOOGLE_CHAT_DEBUG_RAW=1`) routes through the same redaction filter and
+  logs at DEBUG level.
+- **Compliance**: if you plan to connect this bot to a regulated workspace
+  (anything with a data-residency or AI-governance policy), get that approval
+  before the first install.
+- **User OAuth scope**: the per-user attachment flow requests *only*
+  `chat.messages.create` — the minimum that covers `media.upload` plus the
+  follow-up `messages.create`. Tokens are persisted as plain JSON at
+  `~/.hermes/google_chat_user_tokens/<sanitized_email>.json` (filesystem
+  permissions are the protection — same model as the SA key file). Each
+  token is owned by exactly one user; revoke is scoped to that user.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/messaging/homeassistant.md

@@ -0,0 +1,269 @@
+---
+title: Home Assistant
+description: Control your smart home with Hermes Agent via Home Assistant integration.
+sidebar_label: Home Assistant
+sidebar_position: 5
+---
+
+# Home Assistant Integration
+
+Hermes Agent integrates with [Home Assistant](https://www.home-assistant.io/) in two ways:
+
+1. **Gateway platform** — subscribes to real-time state changes via WebSocket and responds to events
+2. **Smart home tools** — four LLM-callable tools for querying and controlling devices via the REST API
+
+## Setup
+
+### 1. Create a Long-Lived Access Token
+
+1. Open your Home Assistant instance
+2. Go to your **Profile** (click your name in the sidebar)
+3. Scroll to **Long-Lived Access Tokens**
+4. Click **Create Token**, give it a name like "Hermes Agent"
+5. Copy the token
+
+### 2. Configure Environment Variables
+
+```bash
+# Add to ~/.hermes/.env
+
+# Required: your Long-Lived Access Token
+HASS_TOKEN=your-long-lived-access-token
+
+# Optional: HA URL (default: http://homeassistant.local:8123)
+HASS_URL=http://192.168.1.100:8123
+```
+
+:::info
+The `homeassistant` toolset is automatically enabled when `HASS_TOKEN` is set. Both the gateway platform and the device control tools activate from this single token.
+:::
+
+### 3. Start the Gateway
+
+```bash
+hermes gateway
+```
+
+Home Assistant will appear as a connected platform alongside any other messaging platforms (Telegram, Discord, etc.).
+
+## Available Tools
+
+Hermes Agent registers four tools for smart home control:
+
+### `ha_list_entities`
+
+List Home Assistant entities, optionally filtered by domain or area.
+
+**Parameters:**
+- `domain` *(optional)* — Filter by entity domain: `light`, `switch`, `climate`, `sensor`, `binary_sensor`, `cover`, `fan`, `media_player`, etc.
+- `area` *(optional)* — Filter by area/room name (matches against friendly names): `living room`, `kitchen`, `bedroom`, etc.
+
+**Example:**
+```
+List all lights in the living room
+```
+
+Returns entity IDs, states, and friendly names.
+
+### `ha_get_state`
+
+Get detailed state of a single entity, including all attributes (brightness, color, temperature setpoint, sensor readings, etc.).
+
+**Parameters:**
+- `entity_id` *(required)* — The entity to query, e.g., `light.living_room`, `climate.thermostat`, `sensor.temperature`
+
+**Example:**
+```
+What's the current state of climate.thermostat?
+```
+
+Returns: state, all attributes, last changed/updated timestamps.
+
+### `ha_list_services`
+
+List available services (actions) for device control. Shows what actions can be performed on each device type and what parameters they accept.
+
+**Parameters:**
+- `domain` *(optional)* — Filter by domain, e.g., `light`, `climate`, `switch`
+
+**Example:**
+```
+What services are available for climate devices?
+```
+
+### `ha_call_service`
+
+Call a Home Assistant service to control a device.
+
+**Parameters:**
+- `domain` *(required)* — Service domain: `light`, `switch`, `climate`, `cover`, `media_player`, `fan`, `scene`, `script`
+- `service` *(required)* — Service name: `turn_on`, `turn_off`, `toggle`, `set_temperature`, `set_hvac_mode`, `open_cover`, `close_cover`, `set_volume_level`
+- `entity_id` *(optional)* — Target entity, e.g., `light.living_room`
+- `data` *(optional)* — Additional parameters as a JSON object
+
+**Examples:**
+
+```
+Turn on the living room lights
+→ ha_call_service(domain="light", service="turn_on", entity_id="light.living_room")
+```
+
+```
+Set the thermostat to 22 degrees in heat mode
+→ ha_call_service(domain="climate", service="set_temperature",
+    entity_id="climate.thermostat", data={"temperature": 22, "hvac_mode": "heat"})
+```
+
+```
+Set living room lights to blue at 50% brightness
+→ ha_call_service(domain="light", service="turn_on",
+    entity_id="light.living_room", data={"brightness": 128, "color_name": "blue"})
+```
+
+## Gateway Platform: Real-Time Events
+
+The Home Assistant gateway adapter connects via WebSocket and subscribes to `state_changed` events. When a device state changes and matches your filters, it's forwarded to the agent as a message.
+
+### Event Filtering
+
+:::warning Required Configuration
+By default, **no events are forwarded**. You must configure at least one of `watch_domains`, `watch_entities`, or `watch_all` to receive events. Without filters, a warning is logged at startup and all state changes are silently dropped.
+:::
+
+Configure which events the agent sees in `~/.hermes/config.yaml` under the Home Assistant platform's `extra` section:
+
+```yaml
+platforms:
+  homeassistant:
+    enabled: true
+    extra:
+      watch_domains:
+        - climate
+        - binary_sensor
+        - alarm_control_panel
+        - light
+      watch_entities:
+        - sensor.front_door_battery
+      ignore_entities:
+        - sensor.uptime
+        - sensor.cpu_usage
+        - sensor.memory_usage
+      cooldown_seconds: 30
+```
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `watch_domains` | *(none)* | Only watch these entity domains (e.g., `climate`, `light`, `binary_sensor`) |
+| `watch_entities` | *(none)* | Only watch these specific entity IDs |
+| `watch_all` | `false` | Set to `true` to receive **all** state changes (not recommended for most setups) |
+| `ignore_entities` | *(none)* | Always ignore these entities (applied before domain/entity filters) |
+| `cooldown_seconds` | `30` | Minimum seconds between events for the same entity |
+
+:::tip
+Start with a focused set of domains — `climate`, `binary_sensor`, and `alarm_control_panel` cover the most useful automations. Add more as needed. Use `ignore_entities` to suppress noisy sensors like CPU temperature or uptime counters.
+:::
+
+### Event Formatting
+
+State changes are formatted as human-readable messages based on domain:
+
+| Domain | Format |
+|--------|--------|
+| `climate` | "HVAC mode changed from 'off' to 'heat' (current: 21, target: 23)" |
+| `sensor` | "changed from 21°C to 22°C" |
+| `binary_sensor` | "triggered" / "cleared" |
+| `light`, `switch`, `fan` | "turned on" / "turned off" |
+| `alarm_control_panel` | "alarm state changed from 'armed_away' to 'triggered'" |
+| *(other)* | "changed from 'old' to 'new'" |
+
+### Agent Responses
+
+Outbound messages from the agent are delivered as **Home Assistant persistent notifications** (via `persistent_notification.create`). These appear in the HA notification panel with the title "Hermes Agent".
+
+### Connection Management
+
+- **WebSocket** with 30-second heartbeat for real-time events
+- **Automatic reconnection** with backoff: 5s → 10s → 30s → 60s
+- **REST API** for outbound notifications (separate session to avoid WebSocket conflicts)
+- **Authorization** — HA events are always authorized (no user allowlist needed, since the `HASS_TOKEN` authenticates the connection)
+
+## Security
+
+The Home Assistant tools enforce security restrictions:
+
+:::warning Blocked Domains
+The following service domains are **blocked** to prevent arbitrary code execution on the HA host:
+
+- `shell_command` — arbitrary shell commands
+- `command_line` — sensors/switches that execute commands
+- `python_script` — scripted Python execution
+- `pyscript` — broader scripting integration
+- `hassio` — addon control, host shutdown/reboot
+- `rest_command` — HTTP requests from HA server (SSRF vector)
+
+Attempting to call services in these domains returns an error.
+:::
+
+Entity IDs are validated against the pattern `^[a-z_][a-z0-9_]*\.[a-z0-9_]+$` to prevent injection attacks.
+
+## Example Automations
+
+### Morning Routine
+
+```
+User: Start my morning routine
+
+Agent:
+1. ha_call_service(domain="light", service="turn_on",
+     entity_id="light.bedroom", data={"brightness": 128})
+2. ha_call_service(domain="climate", service="set_temperature",
+     entity_id="climate.thermostat", data={"temperature": 22})
+3. ha_call_service(domain="media_player", service="turn_on",
+     entity_id="media_player.kitchen_speaker")
+```
+
+### Security Check
+
+```
+User: Is the house secure?
+
+Agent:
+1. ha_list_entities(domain="binary_sensor")
+     → checks door/window sensors
+2. ha_get_state(entity_id="alarm_control_panel.home")
+     → checks alarm status
+3. ha_list_entities(domain="lock")
+     → checks lock states
+4. Reports: "All doors closed, alarm is armed_away, all locks engaged."
+```
+
+### Reactive Automation (via Gateway Events)
+
+When connected as a gateway platform, the agent can react to events:
+
+```
+[Home Assistant] Front Door: triggered (was cleared)
+
+Agent automatically:
+1. ha_get_state(entity_id="binary_sensor.front_door")
+2. ha_call_service(domain="light", service="turn_on",
+     entity_id="light.hallway")
+3. Sends notification: "Front door opened. Hallway lights turned on."
+```
+
+## Troubleshooting
+
+**Environment variables not picked up.**
+The adapter reads credentials from `~/.hermes/.env` (auto-merged at startup) or
+from `config.yaml`. Double-check the file lives under the active Hermes profile
+home and that there's no stray quoting around the URL/token. Restart the gateway
+after editing — env changes are only applied on process start.
+
+
+**REST auth failing (`401 Unauthorized`).**
+The token must be a *Long-Lived Access Token* created from your HA user profile
+page (**Profile → Security → Long-lived access tokens**). Short-lived UI
+session tokens won't work. Also verify the base URL includes the scheme and
+port (e.g. `http://homeassistant.local:8123`) and is reachable from the host
+running Hermes — `curl -H "Authorization: Bearer <token>" <url>/api/` should
+return `{"message": "API running."}`.