docs: cloud models, example provider and cloud tools

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

8 files changed, 36 insertions, 5 deletions

diff --git a/AGENTS.md b/AGENTS.md
index 8d2a91b..0044921 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -3,7 +3,8 @@
 A local text assistant daemon: questions in and streamed replies out on a
 Unix socket, answered by the model already loaded in llama-server, with
 read-only tools and a SQLite history. Nothing leaves the machine except
-what an enabled tool fetches.
+what an enabled tool fetches, and a
+chat the user switched to a cloud model (2026-10-23).
 
 Status (2026-10-16): **text daemon**. The front end is the quickshell
 canvas (`desktop/assistant/` in the quickshell repo, SUPER+Home). Voice
@@ -27,6 +28,11 @@ Tools (2026-09-26): read-only shell-command TOML files in
 built-in settings. Examples in `examples/`. Spec:
 `docs/superpowers/specs/2026-09-26-tools-and-config-design.md`.
 
+Cloud models (2026-10-23): `[[cloud]]` providers in `config.toml`, keys
+from `key_cmd`, ids `provider:model`, chosen per chat and stored on the
+conversation. Only tools with `cloud = true` go to a cloud chat. Spec:
+`docs/superpowers/specs/2026-10-23-cloud-models-design.md`.
+
 Run: `python3 assistant.py` (`--test` for the self-check), or
 `./assistant.sh restart` to replace a running one detached from the
 terminal.
@@ -859,4 +865,6 @@ kokoro-onnx GitHub release `model-files-v1.0`.
 - Ask before acting when anything is ambiguous, and before committing.
 - Package changes belong in `my-slackbuilds`, not here.
 - Never download models or voices without saying which and how big.
-- Everything stays local: no cloud STT/TTS/LLM fallbacks.
+- No silent cloud fallback, ever. A cloud model is used only when the user
+  picks it for a chat; tools reach a cloud chat only with `cloud = true`;
+  audio is always transcribed locally; no cloud STT/TTS.
diff --git a/README.md b/README.md
index 9127aaf..7c7374f 100644
--- a/README.md
+++ b/README.md
@@ -4,8 +4,9 @@ A local text assistant daemon. Questions arrive on a Unix socket, the
 model already loaded in a local llama-server answers, calling read-only
 tools when a question needs them, and the reply streams back token by
 token. Every conversation is kept in a local SQLite history with
-full-text search. The model and the history stay on the machine; only
-tools you enable (weather, web search) reach the network.
+full-text search. The history stays on the machine. So does the model, unless a chat is
+switched to a cloud model you configured; only tools you enable (weather,
+web search) reach the network otherwise.
 
 The front end is the assistant canvas of the quickshell desktop
 (`desktop/assistant/` in the quickshell repo, on SUPER+Home). Anything
@@ -110,6 +111,11 @@ cp -r examples/tools ~/.config/desktop-assistant/
 - `config.toml`: every key is optional, the example lists the defaults.
   `[env]` is added to every tool's environment; put instance URLs and
   key file paths there.
+- `[[cloud]]` in `config.toml`: providers with an OpenAI-compatible API,
+  each with a `key_cmd` that prints its key (see the example). A chat
+  picks a model in the canvas header; a cloud chat is sent its history,
+  attachments and the results of the tools marked `cloud = true`, and
+  nothing from the others. Voice is always transcribed locally.
 - `tools/<name>.toml`: one tool each, enabled by being there. A tool is a
   command run without a shell, its stdout goes back to the model:
 
@@ -117,6 +123,7 @@ cp -r examples/tools ~/.config/desktop-assistant/
 description = "What the tool does, for the model"
 command = ["script.sh", "{param}"]   # looked up in tools/ first, then PATH
 timeout = 10
+cloud = false                        # true: also offered to cloud models
 
 [params.param]
 type = "string"
diff --git a/docs/superpowers/specs/2026-10-23-cloud-models-design.md b/docs/superpowers/specs/2026-10-23-cloud-models-design.md
index 5747c22..64cc8aa 100644
--- a/docs/superpowers/specs/2026-10-23-cloud-models-design.md
+++ b/docs/superpowers/specs/2026-10-23-cloud-models-design.md
@@ -1,6 +1,6 @@
 # Cloud models: design
 
-Date: 2026-10-23. Status: approved, not implemented.
+Date: 2026-10-23. Status: daemon implemented (2026-10-23); quickshell side pending.
 
 ## Goal
 
diff --git a/examples/config.toml b/examples/config.toml
index 85fd846..bf3e3e4 100644
--- a/examples/config.toml
+++ b/examples/config.toml
@@ -15,3 +15,15 @@
 # SEARXNG_URL = "http://searxng.example.org"
 # WEATHER_ENV = "/home/you/.config/udt/weather.env"
 # CALENDAR_DIR = "/home/you/.local/share/calendars"
+
+# Cloud models, picked per chat in the canvas header, never a fallback.
+# One table per provider with an OpenAI-compatible API. key_cmd prints the
+# API key and runs without a shell, once at startup: the key is never
+# stored here. models are the ids the canvas offers; the settings page
+# fetches the list with `assistant.py --cloud-models <name>`. A cloud chat
+# is offered only the tools whose file says cloud = true.
+# [[cloud]]
+# name = "openrouter"
+# url = "https://openrouter.ai/api/v1"
+# key_cmd = "pass show llm/openrouter"
+# models = ["mistralai/mistral-large"]
diff --git a/examples/tools/calc.toml b/examples/tools/calc.toml
index c97ef04..afac35c 100644
--- a/examples/tools/calc.toml
+++ b/examples/tools/calc.toml
@@ -1,5 +1,6 @@
 description = "Calculator: arithmetic, percentages, unit and currency conversion, date math (days between dates). Use it instead of computing yourself."
 command = ["qalc", "-t", "{expression}"]
+cloud = true
 timeout = 10
 
 [params.expression]
diff --git a/examples/tools/now.toml b/examples/tools/now.toml
index c52a4fe..3ef1f87 100644
--- a/examples/tools/now.toml
+++ b/examples/tools/now.toml
@@ -1,2 +1,3 @@
 description = "Current local date and time."
 command = ["date", "+%A %d %B %Y, %H:%M"]
+cloud = true
diff --git a/examples/tools/search.toml b/examples/tools/search.toml
index 7443658..23247f7 100644
--- a/examples/tools/search.toml
+++ b/examples/tools/search.toml
@@ -1,5 +1,6 @@
 description = "Search the web. Use it for facts, news, distances, prices, anything you are not sure about, instead of guessing."
 command = ["search.sh", "{query}"]
+cloud = true
 timeout = 10
 
 [params.query]
diff --git a/examples/tools/weather.toml b/examples/tools/weather.toml
index d9a2e8c..f1e0895 100644
--- a/examples/tools/weather.toml
+++ b/examples/tools/weather.toml
@@ -1,5 +1,6 @@
 description = "Weather now, or the forecast for today or tomorrow. Leave place empty for the user's home."
 command = ["weather.sh", "{place}", "{when}"]
+cloud = true
 timeout = 12
 
 [params.place]