@mulmoclaude/core 5.0.0 → 5.0.1

package/assets/helps/error-recovery.md

@@ -400,11 +400,18 @@ quota / moderation rejection from that provider.
 
 The server appends the provider's own error to the message (e.g.
 `… — 401 Incorrect API key provided`) and logs it under the
-`mulmocast` prefix — read that detail first. Then either add the
-missing key to `.env` (restart the server) or rewrite the script's
-`imageParams` / `movieParams` / speaker providers to ones that have
-keys configured. Don't retry the render unchanged — the same provider
-will fail the same way.
+`mulmocast` prefix — read that detail first. Then either supply the
+missing key or rewrite the script's `imageParams` / `movieParams` /
+speaker providers to ones that have keys configured. Don't retry the
+render unchanged — the same provider will fail the same way.
+
+For `GEMINI_API_KEY`, tell the user to open **Settings → Gemini** and
+paste the key there: it takes effect immediately, with no restart and no
+file to locate, and it wins over a stale value in the shell or a `.env`
+(`config/helps/gemini.md`). The other providers' keys still come from a
+`.env` and need a restart. A render started BEFORE the key was saved
+keeps the environment it was spawned with, so re-run the render rather
+than resuming the old one.
 
 ## MulmoScript narration — wrong voice, ignored direction, or every beat re-recorded
 

package/assets/helps/gemini.md

@@ -36,24 +36,29 @@ The Gemini API has a **free tier that is sufficient for personal use**. Higher-v
 1. Open [Google AI Studio → API keys](https://aistudio.google.com/apikey) and sign in with a Google account.
 2. Click **Create API key**. If prompted, select or create a Google Cloud project (any project will do).
 3. Copy the key — it starts with `AIza…`.
-4. Create (or open) a `.env` file **in the directory you launch MulmoClaude from** — i.e. the directory where you run `npx mulmoclaude` (in a cloned repo, that's the repo root). Add the line:
+4. Open **Settings → Gemini**, paste the key into the field, and click Save. That is the whole step — it takes effect immediately, with no restart and no file to find.
 
-   ```dotenv
-   GEMINI_API_KEY=AIza…your-key…
-   ```
+   The key is written to `~/.mulmoclaude/secrets/GEMINI_API_KEY`, readable only by your user account. It is deliberately outside the `~/mulmoclaude` workspace, which the assistant manages.
 
-   The key stays in your launch directory, not in the `~/mulmoclaude` workspace (which is managed by the assistant). You can also just `export GEMINI_API_KEY=…` in your shell before launching — an exported value takes precedence over the `.env` file.
+### The `.env` route (still supported)
 
-5. Restart MulmoClaude so the new environment variable is picked up.
+A key in a `.env` file keeps working, and is the right choice for a scripted or CI setup. Add `GEMINI_API_KEY=AIza…` to:
+
+- **Started from the icon** (Finder / desktop shortcut): `~/.env`, in your home directory. An icon has no launch directory — macOS starts apps in `/` — so the app is started from home instead. A shell `export` does **not** work on this route: the launcher takes PATH from your login shell and nothing else, so nothing in `~/.zshrc` reaches the app.
+- **Started from a terminal** (`npx mulmoclaude`, or `yarn dev` in a clone): the directory you ran the command in. Here `export GEMINI_API_KEY=…` before launching works too.
+
+Either file needs a restart to be picked up — from the icon, stop the server first via Settings → SERVER → Quit, then click the icon again.
+
+**A key saved in Settings wins** over both the file and the shell. Settings → Gemini says which of the two is in effect, so a value you cannot find is still accounted for.
 
 ## Verifying It's Active
 
-The quickest check: switch to the **Artist** role and ask for _"an image of a red panda"_. If a real image appears in the canvas (instead of an italic text marker or a disabled-role hint), the key is wired up correctly.
+Settings → Gemini states whether a key is configured and where it came from. For an end-to-end check, switch to the **Artist** role and ask for _"an image of a red panda"_: if a real image appears in the canvas (instead of an italic text marker or a disabled-role hint), the key is wired up correctly.
 
-You can also inspect the server log on startup: a `GEMINI_API_KEY not set — image / audio / video generation is unavailable` warning means the key was not found (missing, misread, or placed outside your launch directory).
+You can also inspect the server log on startup: a `GEMINI_API_KEY not set — image / audio / video generation is unavailable` warning means the key was not found. The warning names the exact `.env` path this launch reads, so a key that is set but in the wrong file shows up as a path you did not expect.
 
 ## Security
 
-- The key lives in your local `.env` file. MulmoClaude never uploads it to its own servers or to Anthropic — requests go directly from your machine to Google.
+- The key stays on your machine — in `~/.mulmoclaude/secrets/` when saved from Settings, or in your own `.env` file. MulmoClaude never uploads it to its own servers or to Anthropic; requests go directly from your machine to Google.
 - Treat the key like a password. Anyone who sees it can make billable API calls against your Google account.
 - If you suspect a key has leaked, revoke it from [Google AI Studio → API keys](https://aistudio.google.com/apikey) and generate a new one.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mulmoclaude/core",
-  "version": "5.0.0",
+  "version": "5.0.1",
   "description": "Shared server-side core for MulmoClaude and MulmoTerminal — the always-shipped-together subsystems consolidated behind subpath exports so the two hosts can't drift. Server-only except the browser-safe ./artifacts, ./whisper/client, ./workspace-setup/slug, ./translation/client, ./remote-view, ./remote-host and ./plugin-vue entries. All host specifics are injected.",
   "repository": {
     "type": "git",