State env var defaults in plugin.yaml install prompts

Every optional_env description now carries its default — at install
time the prompt is the only documentation the user sees. TOKEN joins
the prompts as an equal alternative to login+password, LOGIN/PASSWORD
say what leaving them blank means (token auth instead), and
ALLOW_ALL_USERS is asked before ALLOWED_USERS since the two are
mutually exclusive. AGENTS.md records the defaults rule; the README
install note no longer enumerates just three prompts.

AGENTS.md

@@ -183,7 +183,11 @@ the `CHATTO_*` environment variable (upper-cased config_key). Resolution order
 per instance: env var → extra → default. Declaring a field is enough for the
 adapter, the env-enablement seeding and the setup wizard to pick it up;
 `plugin.yaml` additionally repeats the env names as wizard prompts, so keep
-those entries in step.
+those entries in step. Every `optional_env` entry states its default right in
+its description (`(default: …)`): at install time the prompt is all the user
+sees — "what happens if I leave this empty?" must be answerable without
+opening README.md. Required entries have no default to state; they say what
+happens when left blank instead (see `CHATTO_BASE_URL`).
 
 When adding or renaming a field, also update the environment-variable table in
 README.md — and document each option's default next to it, for env vars

README.md

@@ -65,7 +65,7 @@ hermes plugins install https://gogs.netdome.biz/paul/hermes-chatto-plugin.git
 
 Hermes clones the plugin from that Git URL into its platform-plugin directory and auto-discovers it on gateway startup — no manual registration needed.
 
-> **Note:** During install Hermes reads the plugin's declared details from `plugin.yaml` and prompts you for them — server URL, login, and password. What you enter there is written as the plugin's first configuration; secrets should still live in `~/.hermes/.env` (see [Configuration](#configuration)).
+> **Note:** During install Hermes reads the env vars declared in the plugin's `plugin.yaml` (`requires_env` / `optional_env`) and prompts you for each — connection details plus a few behaviour options. Your answers are written to `~/.hermes/.env`; secrets should still live there only (see [Configuration](#configuration)).
 
 ### Option B: Manual Installation
 

plugin.yaml

@@ -16,26 +16,32 @@ requires_env:
     prompt: "Chatto server Base URL"
     password: false
   - name: CHATTO_LOGIN
-    description: "Chatto login (username)"
+    description: "Chatto login (username); leave blank only when you authenticate with CHATTO_TOKEN instead"
     prompt: "Chatto login"
     password: false
   - name: CHATTO_PASSWORD
-    description: "Chatto password"
+    description: "Chatto password; leave blank only when you authenticate with CHATTO_TOKEN instead"
     prompt: "Chatto password"
     password: true
 optional_env:
+  - name: CHATTO_TOKEN
+    description: "Existing bearer token — alternative to CHATTO_LOGIN + CHATTO_PASSWORD (default: none)"
+    prompt: "Existing bearer token (or empty)"
+    password: true
   - name: CHATTO_HOME_CHANNEL
     description: "Room ID for cron / notification delivery (defaults to the first watched room)"
     prompt: "Home room ID (or empty)"
     password: false
-  - name: CHATTO_ALLOWED_USERS
-    description: "Comma-separated Chatto logins allowed to talk to the agent"
-    prompt: "Allowed users (comma-separated)"
-    password: false
+  # Asked before CHATTO_ALLOWED_USERS: a "yes" here makes the user list moot,
+  # and the two are mutually exclusive (hermes_validate_config rejects both).
   - name: CHATTO_ALLOW_ALL_USERS
-    description: "Allow any Chatto user to talk to the agent (true/false)"
+    description: "Allow any Chatto user to talk to the agent (default: false)"
     prompt: "Allow all users? (true/false)"
     password: false
+  - name: CHATTO_ALLOWED_USERS
+    description: "Comma-separated Chatto logins allowed to talk to the agent (default: none — denies everyone unless CHATTO_ALLOW_ALL_USERS=true)"
+    prompt: "Allowed users (comma-separated)"
+    password: false
   - name: CHATTO_REQUIRE_MENTION
     description: "Only respond to @mentions in channels (default: false). Group-kind rooms and DMs always get a response."
     prompt: "Require mention in rooms? (true/false)"
@@ -45,7 +51,7 @@ optional_env:
     prompt: "Auto-thread replies? (true/false)"
     password: false
   - name: CHATTO_FREE_RESPONSE_CHANNELS
-    description: "Comma-separated room IDs where the bot responds without being tagged"
+    description: "Comma-separated room IDs where the bot responds without being tagged (default: none)"
     prompt: "Free-response room IDs (comma-separated)"
     password: false
   - name: CHATTO_REACTIONS