vibeaudio 0.5.0 → 0.6.1

package/README.md

@@ -22,21 +22,25 @@ AI coding agents take 15–45 seconds to reason, read files and write code. Star
 
 * 🧮 **Pure synthesis, zero MP3s.** Every note, chord and pad is generated in code — no audio assets, no npm dependencies, no `node-gyp`.
 * 🎼 **A different arrangement per project.** Your working directory seeds the progression, bass line and melody, so each repo has its own sound and keeps it.
-* 🛡️ **A grace window.** Fast commands stay 100% silent — music starts only past 1.5s (`--grace`).
 * 📈 **Escalating layers.** Tier 1 (0–15s) gentle intro → Tier 2 (15–45s) main groove → Tier 3 (45s+) deep focus. You can hear how deep into the task the agent is.
 * 🔔 **Outcome-aware chimes.** Ascending on success, a soft descending minor chord on failure, and **silence on `Ctrl+C`** — an abort is never reported as done.
 * ✋ **A "your turn" chime.** When Claude Code stops to ask permission (or an MCP server asks for input), the music pauses and a rising two-note chime asks for you; it picks back up once you've answered.
+* 🔌 **Universal drop-in.** Hooks for **Claude Code, Codex, Cursor, Grok, Gemini CLI, Copilot CLI and Qwen Code**; MCP for **Claude Desktop and Antigravity**; the wrapper (`vibe <command>`) for anything else.
+
+<details>
+<summary><b>And the quieter four</b> — silence on fast commands, several sessions at once, exit codes, the HUD</summary>
+
+* 🛡️ **A grace window.** Fast commands stay 100% silent — music starts only past 1.5s (`--grace`).
 * 🪟 **Several sessions, one soundtrack.** Run as many terminals of the same agent as you like: the music plays while *any* of them is working, and each finishes with its own chime. One session ending, pausing for a permission dialog or being interrupted never cuts off another that's still going.
 * 🧮 **Honest exit codes.** Your command's status passes straight through (`130` on `Ctrl+C`), so `vibe claude && next-step` behaves exactly as it would without the wrapper.
 * 🌊 **Terminal title HUD.** A live ASCII wave and elapsed timer in the window title, where it can't corrupt a full-screen TUI.
-* 🔌 **Universal drop-in.** Hooks for **Claude Code, Codex, Cursor, Grok, Gemini CLI, Copilot CLI and Qwen Code**; MCP for **Claude Desktop and Antigravity**; the wrapper (`vibe <command>`) for anything else.
+
+</details>
 
 ### 🎼 Every project gets its own arrangement
 
 VibeAudio seeds the composition from your **project directory**. The repo you're in picks the chord progression, the bass line, the melodic contour, and where the ornaments land — so `~/work/api` and `~/side/game` genuinely sound different, while each one sounds the *same every time you come back to it*.
 
-That's a deliberate choice. Focus music has one job: **be ignorable.** Music that reinvents itself every run keeps pulling your ear back, which is the opposite of what you want while reading an agent's output. Familiar-per-project gives you variety across contexts and predictability within one — by your third session in a repo, its loop has faded into the furniture.
-
 Pin or explore arrangements when you want to:
 
 ```bash
@@ -44,8 +48,15 @@ vibe --seed 42 --preview jazz    # audition one specific arrangement
 export VIBE_SEED=7               # pin the same sound everywhere
 ```
 
+<details>
+<summary><b>Why the same sound every time, rather than something new — and what "procedural" actually means</b></summary>
+
+That's a deliberate choice. Focus music has one job: **be ignorable.** Music that reinvents itself every run keeps pulling your ear back, which is the opposite of what you want while reading an agent's output. Familiar-per-project gives you variety across contexts and predictability within one — by your third session in a repo, its loop has faded into the furniture.
+
 **How "procedural" actually works** — worth being precise, since it shapes what you'll hear. Each genre is **synthesized from code** (oscillators, chord tables, envelopes rendered to PCM), not shipped as audio files. The seed selects among *hand-written, human-checked* variants — three progressions per genre, each diatonic to that genre's key, plus seeded ornament placement — so it never invents harmony and can't wander out of key. The chosen arrangement is rendered once per project, cached under `~/.vibeaudio/cache/`, and looped. Within a session you're hearing a 6–8 second bar repeat that gains layers as you cross the tier boundaries.
 
+</details>
+
 ---
 
 ## 📋 Requirements
@@ -147,6 +158,13 @@ Choose your volume level:
   4. 📢 Loud (75%)         — Audible across the room
 ```
 
+**Press `p` to hear the highlighted genre** — auditioning is just a keypress, and moving on replaces it.
+
+Installed tools sort to the top, and the list is a shortcut rather than a compatibility list: **`vibe` wraps any command at all**, and "Custom command..." takes one you type.
+
+<details>
+<summary><b>Picking a hook-capable agent asks two more questions</b></summary>
+
 Pick **Claude Code** or **Codex** and it asks how the music should run — hooks or just this session — and the hooks branch then offers [reactive mode](#reactive-mode-opt-in) too:
 
 ```
@@ -159,9 +177,11 @@ Should the music react to what the agent is doing?
   2. Reactive             — Intensity follows the tool in use - noticeable, by design
 ```
 
-Choosing hooks installs them for the tool you picked, then launches it — the same thing `vibe --genre <g> --volume <n> --reactive --install-hooks` does, without memorising flags. Once they're installed the first question becomes **Just launch it** / **Reconfigure the hooks**, and launching skips the genre and volume prompts, since the hooks own those.
+Choosing hooks installs them for the tool you picked, then launches it — the same thing `vibe --genre <g> --volume <n> --reactive --install-hooks` does, without memorising flags. Once they're installed the first question becomes **Just launch it** / **Reconfigure the hooks**, and launching skips the genre and volume prompts, since your saved default already answers those (`vibe --genre zen` changes it any time).
 
-Installed tools sort to the top. The list is a shortcut, not a compatibility list — **`vibe` wraps any command at all**, and "Custom command..." takes one you type (quoted arguments survive intact). Adding an entry is one line in [`src/interactive.js`](src/interactive.js).
+Adding an entry to the launcher is one line in [`src/interactive.js`](src/interactive.js).
+
+</details>
 
 ---
 
@@ -176,12 +196,17 @@ Once hooks are installed they take over: running `vibe claude` (or `vibe codex`)
 ```bash
 vibe --install-hooks                             # every agent found on this machine
 vibe --install-hooks --tools codex               # or just one of them
-vibe --genre jazz --volume 25 --install-hooks    # pin the genre and volume
+vibe --genre jazz --volume 25 --install-hooks    # install, and save these as your default
 vibe --install-hooks --dry-run                   # show what would change, write nothing
 ```
 
 **It auto-detects.** With no `--tools`, VibeAudio wires up each supported agent it finds on your machine — one counts as present when its config directory exists or its CLI is on your `PATH`. `--tools claude,codex,cursor,grok,gemini,copilot,qwen` overrides that. Add `--dry-run` to see, per event, what would be added or changed in each file before anything is written.
 
+That's it — run your agent normally, with no `vibe` prefix.
+
+<details>
+<summary><b>Which file and which events, per agent</b> — seven dialects, all written for you</summary>
+
 Each tool spells its events its own way, and VibeAudio writes whichever dialect the file expects:
 
 | | File | Music starts | Music stops + chime | Reactive (opt-in) |
@@ -205,9 +230,11 @@ Where an agent reports more than start and stop, VibeAudio listens for that too
 | **Qwen Code** | `PermissionRequest` | `PostToolUse`, `PostToolUseFailure` | `StopFailure` | `SessionEnd` |
 | **Cursor, Grok** | — | — | — | — |
 
-That's it — run your agent normally, with no `vibe` prefix.
+</details>
+
+<details>
+<summary><b>Six things that differ per agent</b> — only the first one needs anything from you</summary>
 
-Six things differ per agent, and none of them need any action from you except the first:
 
 | | |
 | :--- | :--- |
@@ -217,24 +244,32 @@ Six things differ per agent, and none of them need any action from you except th
 | **Only Cursor can play the failure chime** | Its stop event reports whether the turn completed, aborted or errored. The others send no verdict, so a turn there always ends on the success chime — VibeAudio won't invent a failure the agent never claimed. |
 | **Grok and Copilot CLI get a file of their own** | Each reads every `*.json` in its `hooks/` directory, so VibeAudio writes `vibeaudio.json` rather than merging into anyone else's — which makes uninstalling it a delete, and leaves no backup file behind. Copilot's honours `COPILOT_HOME`. |
 
+</details>
+
 ### Several sessions at once
 
 Every session of an agent is tracked separately, by the session id in its hook payload, so two terminals (or a terminal and the desktop app) share one soundtrack instead of fighting over it:
 
 * **The music plays while any session is working.** A second prompt doesn't restart it, and it stops only when the last working session finishes.
-* **More sessions, more music.** Two sessions working at once plays at least tier 2 and three or more plays tier 3 — the same piece with more layers, arriving at the next loop boundary and easing off as sessions finish. It only ever raises the tier, so it works alongside time escalation and [reactive mode](#reactive-mode-opt-in).
 * **Every session gets its own chime.** A quick question that finishes while another agent is still busy chimes "done" and the music carries on underneath.
+
+<details>
+<summary><b>The rest of how sessions share one stream</b></summary>
+
+* **More sessions, more music.** Two sessions working at once plays at least tier 2 and three or more plays tier 3 — the same piece with more layers, arriving at the next loop boundary and easing off as sessions finish. It only ever raises the tier, so it works alongside time escalation and [reactive mode](#reactive-mode-opt-in).
 * **Dialogs and Esc are per session.** A permission dialog in one terminal plays the "your turn" chime but only pauses the music once *every* session is waiting; Esc ends just that session's turn.
 * **Crashed agents can't hold it hostage.** A session that never sent `Stop` is dropped after 15 minutes, the same ceiling the background player stops at.
 
 Sessions with no id in their payload share a single slot, so they behave as one. VibeAudio keeps one stream: per-session genres or several streams mixed together aren't supported.
 
-> **No restart needed, even mid-session — for Claude Code, Codex, Cursor and Grok.** Each re-reads its hook file every time a hook fires, so changes land on your **next prompt**. A daemon already playing keeps its old settings until that prompt replaces it — at most the tail of one turn. Whether an open Gemini CLI, Copilot CLI or Qwen Code session does the same hasn't been checked, so start a new session there to be sure.
+</details>
 
-> **One player is shared.** They all drive the same background player, so if you prompt two agents at once, the last prompt owns the music. One person, one set of speakers — deliberate, not a limitation being worked around.
+> **No restart needed, even mid-session — for Claude Code, Codex, Cursor and Grok.** Each re-reads its hook file every time a hook fires, so changes land on your **next prompt**. A daemon already playing keeps its old settings until that prompt replaces it — at most the tail of one turn. Whether an open Gemini CLI, Copilot CLI or Qwen Code session does the same hasn't been checked, so start a new session there to be sure.
 
 > **The Claude Code desktop app is covered too**, not just the terminal — both read the same `~/.claude/settings.json`. (The separate **Claude Desktop** chat app is a different product with no hooks; that one needs [MCP](#-everything-else-claude-desktop-antigravity-via-mcp).)
 
+> **One player is shared.** Prompt two agents at once and the last prompt owns the music. One person, one set of speakers — deliberate, not a limitation being worked around.
+
 ### `/vibe` inside Claude Code
 
 Installing the Claude Code hooks also adds a `/vibe` command (`~/.claude/commands/vibe.md`), so you can control the music without leaving the session:
@@ -251,23 +286,32 @@ It asks Claude to run the matching `vibe` command, so Claude Code will ask permi
 
 ### Changing the sound later
 
-Re-run the install with the settings you want. It replaces the existing entry rather than adding a second one:
+One command, and it reaches everything:
 
 ```bash
-vibe --genre electronic --volume 25 --install-hooks
+vibe --genre electronic --volume 25
 ```
 
-The change applies to your next prompt — no restart. Audition first with `vibe --preview electronic`.
+That saves your default to `~/.vibeaudio/config.json`. **Installed hooks read it on their next prompt** — nothing to reinstall, nothing to restart. The same file is what the wrapper and the MCP server use, so there is one answer to "what genre am I on" rather than three. `vibe --status` shows it.
+
+Audition before you commit: `vibe --preview electronic`.
 
-**The flags compose** — set everything you want in one command, including [reactive mode](#reactive-mode-opt-in):
+A flag still beats an environment variable, which still beats the saved file — so a one-off stays a one-off:
 
 ```bash
-vibe --genre jazz --volume 25 --reactive --install-hooks
+vibe --genre 8bit npm test      # this run only, nothing saved
 ```
 
-Two things to know: the reinstall **replaces** the whole entry, so flags you don't repeat are dropped (leave off `--reactive` and reactive mode goes away). And music already playing keeps the old genre until the next prompt swaps the daemon — `pkill -f "vibeaudio.js --daemon"` cuts it short.
+**Coming from an older install?** Its genre and volume were frozen into the hook entries. The first `vibe --install-hooks` after upgrading carries them over into the config file, so nothing about your music changes — unless you name a new genre or volume, or have already saved one.
+
+[Reactive mode](#reactive-mode-opt-in) is the exception, because it isn't a setting the music reads — it decides which hooks exist at all. Turning it on or off means an install:
+
+```bash
+vibe --reactive --install-hooks     # on
+vibe --install-hooks                # off again
+```
 
-> **`VIBE_GENRE` / `VIBE_VOLUME` won't change an installed hook.** They're read once, at install time, and written into the hook command — so exporting a new value later does nothing until you reinstall. The same goes for `vibe --genre <name>` on its own: with no command after it that opens the launcher menu, which asks for a genre and uses its own answer. Changing hook music always means re-running `--install-hooks`.
+Music already playing keeps the old genre until the next prompt swaps the daemon — `vibe --stop` cuts it short.
 
 Removing them is one command:
 
@@ -293,9 +337,10 @@ Each agent names its tools differently, and all the vocabularies are mapped. **M
 
 Changes land at the next loop boundary, so it shifts musically rather than cutting mid-bar. Without a tool signal it falls back to time-based escalation.
 
-**This is off by default on purpose.** Music that moves every time the agent switches tools is music you *notice* — which is the opposite of what focus audio is for. Try it, but if you catch yourself listening to it instead of reading, reinstall without `--reactive` (which removes the `PreToolUse` hook again).
+**Off by default on purpose** — music that moves every time the agent switches tools is music you *notice*, which is the opposite of what focus audio is for. Try it; if you catch yourself listening instead of reading, reinstall without `--reactive` and the `PreToolUse` hook goes away again.
 
-**What the installer will and won't do to your config:**
+<details>
+<summary><b>What the installer will and won't do to your config</b> — it edits a file you own, so here is the whole of it</summary>
 
 * **Merges, never replaces.** Other tools' hooks are left untouched and keep their position in the file — which is what Codex keys its trust records by.
 * **Backs up first, once.** The first install copies your file alongside as `*.vibeaudio.bak`. Later installs leave it alone — re-copying would overwrite your real pre-VibeAudio config with a copy of VibeAudio's own last install.
@@ -303,13 +348,15 @@ Changes land at the next loop boundary, so it shifts musically rather than cutti
 * **Refuses rather than clobbers.** Malformed JSON aborts the write; a temporary `npx` checkout is rejected outright, since the hook records an absolute path that npm's cache eviction would later delete.
 * **Can't run away.** The background player is capped at 15 minutes, so a missed stop event can't leave music looping.
 
+</details>
+
 ---
 
 ## 🖥️ Everything Else (Claude Desktop, Antigravity… via MCP)
 
 **Claude Code, [Codex](https://github.com/openai/codex), [Cursor](https://cursor.com/docs/hooks), [Grok](https://docs.x.ai/build/features/hooks), [Gemini CLI](https://github.com/google-gemini/gemini-cli), [Copilot CLI](https://docs.github.com/en/copilot/reference/hooks-configuration) and [Qwen Code](https://github.com/QwenLM/qwen-code) have hook systems, and `--install-hooks` writes to all seven** — use [hooks](#-agent-hooks-no-wrapper-needed) there, they're strictly better. This section is for everything else. MCP is the way in: it's plain stdio JSON-RPC, so the setup is identical everywhere and only the config file differs.
 
-> **This is weaker than hooks, by nature.** Hooks fire on an event — the music always starts when you submit a prompt. MCP tools are *model-invoked*: the assistant has to decide to call `vibe_play`, and to remember `vibe_stop` when it's done. The server tells it when to do that (via the MCP `instructions` field), but it's a suggestion, not a guarantee — expect the occasional silent turn, and say "play some focus music while you work on this" if you want it reliably. **On any of the seven agents above, use [hooks](#-agent-hooks-no-wrapper-needed) instead.**
+> **This is weaker than hooks, by nature.** Hooks fire on an event; MCP tools are *model-invoked*, so the assistant has to decide to call `vibe_play` and remember `vibe_stop`. Expect the occasional silent turn — say "play some focus music while you work on this" if you want it reliably. **On any of the seven agents above, use [hooks](#-agent-hooks-no-wrapper-needed) instead.**
 
 Use an **absolute path**, not the bare `vibe` command: GUI apps launched from Finder don't inherit your shell's `PATH`, and version managers like `fnm` or `nvm` put `vibe` on a per-shell path that won't resolve. Print yours with:
 
@@ -337,6 +384,11 @@ Where the file lives:
 | **Claude Desktop** (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
 | **Antigravity, VS Code, Zed, …** | that app's own MCP settings — same JSON shape |
 
+Restart the app afterwards.
+
+<details>
+<summary><b>Codex's TOML, and older Gemini CLI releases</b></summary>
+
 Codex uses TOML rather than JSON, in `~/.codex/config.toml` — but it has hooks, so [use those instead](#-agent-hooks-no-wrapper-needed) unless you specifically want model-invoked music:
 
 ```toml
@@ -345,15 +397,17 @@ command = "node"
 args = ["/absolute/path/from/the/command/above", "--mcp"]
 ```
 
-Restart the app afterwards. Older Gemini CLI releases predate its hook system (0.10.0 has none) — if you're on one and can't upgrade, the same JSON goes in `~/.gemini/settings.json`.
+Older Gemini CLI releases predate its hook system (0.10.0 has none) — if you're on one and can't upgrade, the same JSON goes in `~/.gemini/settings.json`.
+
+</details>
 
 ### Changing the genre here
 
-`vibe --genre` doesn't apply — the app launches the server, not you. Two ways instead:
+**Set it like anywhere else.** `vibe --genre jazz --volume 25` saves the default the server reads, and it reads it per request — so the next `vibe_play` picks it up with no restart and no config edit, even though the app launched the server and you didn't.
 
-**Just ask.** `vibe_play` takes a genre, so "play some jazz while you work on this" is enough, no config edit and no restart.
+**Or just ask.** `vibe_play` takes a genre, so "play some jazz while you work on this" is enough. A genre the assistant passes wins over the saved default.
 
-**Or set a default in the config's `env` block**, since a GUI app won't inherit `VIBE_GENRE` from your shell. Most clients support `env` alongside `command`/`args`:
+**Or pin one in the config's `env` block**, if you want this client to differ from the rest of your machine — a GUI app won't inherit `VIBE_GENRE` from your shell. Most clients support `env` alongside `command`/`args`:
 
 ```json
 "env": { "VIBE_GENRE": "jazz", "VIBE_VOLUME": "25" }
@@ -365,7 +419,7 @@ VIBE_GENRE = "jazz"
 VIBE_VOLUME = "25"
 ```
 
-Restart the app afterwards. A genre the assistant passes to `vibe_play` still wins over this default.
+Restart the app afterwards — this one is read from the environment the server was launched with, so unlike the saved default it can't change under a running client.
 
 #### Exposed MCP Tools:
 * `vibe_play`: Start procedural focus music (`genre`: `lofi`, `synthwave`, `8bit`, `electronic`, `jazz`, `zen`, `piano`, `drone`, `random`; `volume`: `5-100`).
@@ -410,28 +464,43 @@ vibe --genre random claude       # Surprise vibe each run
 
 ### ⚙️ Set Your Favorite Genre as Default
 
-How you change it depends on how you run VibeAudio — **a shell `export` only reaches the wrapper**:
+```bash
+vibe --genre jazz --volume 25
+```
 
-| You run it via | Change the genre with |
-| :--- | :--- |
-| **Wrapper** (`vibe <command>`) | `export VIBE_GENRE=jazz` — or `--genre` per run |
-| **Agent hooks** (Claude Code, Codex, Cursor, Grok) | re-run `vibe --genre jazz --install-hooks` — [why](#changing-the-sound-later) |
-| **MCP** (Gemini CLI, Claude Desktop, …) | ask the assistant, or the config's `env` block — [how](#changing-the-genre-here) |
+Saved to `~/.vibeaudio/config.json` and read by all three ways of running VibeAudio — wrapper, agent hooks, MCP. It applies on your next prompt.
 
 ```bash
-export VIBE_GENRE=jazz     # or synthwave, 8bit, electronic, zen, piano, drone, random
+vibe --genre jazz          # lofi, synthwave, 8bit, electronic, jazz, zen, piano, drone, random
+vibe --volume 25           # or --whisper / --quiet / --loud
+vibe --chime-volume 70
+vibe --status              # what's saved, and what's overriding it
 ```
 
+An `export VIBE_GENRE=jazz` still works and takes precedence in that shell — useful for one terminal you want different, not needed for a default any more.
+
+**One project that should sound different:**
+
+```bash
+cd ~/work/api
+vibe --genre zen --here      # this directory and everything under it
+```
+
+Your global default is untouched, and an agent launched from a subdirectory still gets it — the lookup walks up, so `~/work/api/src` finds what you saved at `~/work/api`. `vibe --status` says which one answered (`saved for this project` / `saved` / `default`).
+
+The full order, highest first: **a flag** → **an environment variable** → **`--here`** → **your global default** → `lofi` at 40%.
+
 ---
 
 ## ⚙️ Options & Flags
 
 | Flag | Description | Default |
 | :--- | :--- | :--- |
-| `-g, --genre <name>` | Music style: `lofi`, `synthwave`, `8bit`, `electronic`, `jazz`, `zen`, `piano`, `drone`, `random` | `lofi` |
-| `-v, --volume <5-100>` | Set playback volume | `40` |
+| `-g, --genre <name>` | Music style: `lofi`, `synthwave`, `8bit`, `electronic`, `jazz`, `zen`, `piano`, `drone`, `random`. With no command after it, saves your default | `lofi` |
+| `-v, --volume <5-100>` | Set playback volume. With no command after it, saves your default | `40` |
 | `-cv, --chime-volume <5-100>` | Set independent completion chime volume | `volume × 1.1`, kept within 35–65 |
 | `--grace <ms>` | Silence window before music starts | `1500` |
+| `--here` | With a saved setting: this directory tree only, not everywhere | off |
 | `--seed <n>` | Force a specific arrangement | derived from the project directory |
 | `--whisper` | Quick preset: 15% volume (headphones / late night) | — |
 | `--quiet` | Quick preset: 25% volume (focus / open office) | — |
@@ -454,7 +523,8 @@ export VIBE_GENRE=jazz     # or synthwave, 8bit, electronic, zen, piano, drone,
 | `--version` | Show version | — |
 
 ### ⚙️ Environment Variables
-Set persistent defaults in your `~/.zshrc` or `~/.bashrc`:
+
+**Defaults live in `~/.vibeaudio/config.json` now** — `vibe --genre jazz` is the short way to set one. These override it for a single shell, which is what you want for one terminal that should sound different, or for a machine you don't want writing config at all:
 
 ```bash
 export VIBE_GENRE=jazz          # lofi, synthwave, 8bit, electronic, jazz, zen, piano, drone, random
@@ -467,7 +537,7 @@ export VIBE_DISABLE=1           # Mute, without uninstalling anything
 
 **`VIBE_DISABLE=1` is for a shell you always want quiet** — a CI job, a shared machine, a terminal profile you keep silent. It's read at playback time and covers hooks, wrapper and MCP alike.
 
-**For a call that's ringing right now, use `vibe --mute` instead.** An environment variable can't help there: a hook runs as a child of your agent and inherits the environment the agent had *when it launched*, so exporting `VIBE_DISABLE` in another terminal reaches nothing already running — and restarting your agent is exactly what you can't do mid-call.
+**For a call that's ringing right now, use `vibe --mute` instead** — an exported variable can't reach a hook that's already running.
 
 ```bash
 vibe --mute        # silent now, music returns by itself in an hour
@@ -476,11 +546,16 @@ vibe --mute 0      # stay off until I say otherwise
 vibe --unmute      # end it early
 ```
 
-`--mute` writes a flag file, which crosses process boundaries where a variable cannot, and stops whatever is playing on the spot. Your hooks and settings are untouched, so there's nothing to put back afterwards.
+It stops whatever is playing on the spot, leaves your hooks and settings untouched, and **expires after an hour** so you can't forget it. `--preview` still plays either way — that one is an explicit request to hear something.
+
+<details>
+<summary><b>Why a file, and why it expires</b></summary>
 
-**It expires after an hour by default, and that's deliberate.** A call is a bounded thing; a mute you forget about is worse than no mute, because the tool just stops working and nothing ever tells you why. Expiring means the worst case is "music came back sooner than I wanted" rather than a week of silence you never diagnose. `--mute 0` opts into indefinite explicitly, and `vibe --status` always shows how much of the window is left.
+A hook runs as a child of your agent and inherits the environment the agent had *when it launched*, so exporting `VIBE_DISABLE` in another terminal reaches nothing already running — and restarting your agent is exactly what you can't do mid-call. `--mute` writes a flag file, which crosses that boundary where a variable cannot.
 
-Either way, `--preview` still plays: that one is an explicit request to hear something.
+The expiry is deliberate too. A call is a bounded thing; a mute you forget about is worse than no mute, because the tool just stops working and nothing ever tells you why. Expiring means the worst case is "music came back sooner than I wanted" rather than a week of silence you never diagnose. `--mute 0` opts into indefinite explicitly, and `vibe --status` always shows how much of the window is left.
+
+</details>
 
 ---
 
@@ -522,7 +597,7 @@ This needs a PulseAudio-compatible sound server on **your local machine**: a Lin
 If the second connection fails with the socket "already in use", an earlier session left it behind: `rm /tmp/vibe-pulse.sock` on the server, or set `StreamLocalBindUnlink yes` in the server's `sshd_config`. If `paplay` says access denied, your local PulseAudio requires its cookie — copy `~/.config/pulse/cookie` to the same path on the server.
 
 **Volume flag does nothing**
-Shouldn't happen any more — where the player can't attenuate (`aplay`, PowerShell), the gain is baked into the audio instead. If you changed `--volume` and hear no difference, you're most likely on hooks, which ignore the wrapper's flags: re-run `vibe --volume 25 --install-hooks`.
+Shouldn't happen any more — where the player can't attenuate (`aplay`, PowerShell), the gain is baked into the audio instead. A `--volume` change lands at the next loop boundary, and on hooks at your next prompt; `vibe --status` shows the volume in effect and what set it.
 
 ---
 
@@ -573,14 +648,17 @@ The last block is detected from your own `PATH`, so it answers "will this work w
 ```bash
 vibe --uninstall-hooks          # 1. unwire every agent, and stop any player still running
 npm rm -g vibeaudio             # 2. remove the CLI
-rm -rf ~/.vibeaudio             # 3. optional: cached audio + daemon state
+rm -rf ~/.vibeaudio             # 3. optional: cached audio, saved settings, daemon state
 ```
 
+<details>
+<summary><b>Why that order, and what stays behind</b></summary>
+
 Step 1 also **stops a background player that's still going**. That matters: once the hooks are gone nothing will ever send the `Stop` event, and after step 2 there's no `vibe` left to stop it with — music would simply play on until its 15-minute cap. If you ever need to do it by hand: `pkill -f "vibeaudio.js --daemon"`.
 
 > **Order matters.** `npm rm -g` deletes the binary but not your hook config. Removing the package first strands hook entries that point at a path that no longer exists, and your agent will run a failing hook on every prompt. If you already did it in the wrong order, reinstall, run `vibe --uninstall-hooks`, then remove again — or delete the `vibeaudio` entries from `~/.claude/settings.json`, `~/.codex/hooks.json`, `~/.cursor/hooks.json`, `~/.gemini/settings.json` and `~/.qwen/settings.json` by hand, and delete `~/.grok/hooks/vibeaudio.json`, `~/.copilot/hooks/vibeaudio.json` and `~/.claude/commands/vibe.md`.
 
-Step 3 only reclaims disk — the audio cache, pruned to the 3 most recent projects — and it's regenerated on next use, so skip it if you're reinstalling.
+Step 3 reclaims disk — the audio cache, pruned to the 3 most recent projects — and drops your saved genre and volume. Both come back on their own, so skip it if you're reinstalling.
 
 **Two things are deliberately left behind:**
 
@@ -591,6 +669,8 @@ Step 3 only reclaims disk — the audio cache, pruned to the 3 most recent proje
 
 Apart from those two, the three commands above remove everything VibeAudio writes.
 
+</details>
+
 ---
 
 ## 🤝 Contributing

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "vibeaudio",
-  "version": "0.5.0",
-  "description": "Procedural focus music while your AI coding tools (Claude Code, Codex, Cursor, Grok, Gemini, Copilot) think — a different arrangement per project.",
+  "version": "0.6.1",
+  "description": "Procedural focus music while your AI coding tools (Claude Code, Codex, Cursor, Grok, Gemini, Copilot) think \u2014 a different arrangement per project.",
   "bin": {
     "vibeaudio": "bin/vibeaudio.js",
     "vibe": "bin/vibeaudio.js"
@@ -9,7 +9,8 @@
   "main": "src/cli.js",
   "scripts": {
     "test": "node test/test-synth.js",
-    "start": "node bin/vibeaudio.js"
+    "start": "node bin/vibeaudio.js",
+    "postinstall": "node scripts/postinstall.js"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
@@ -21,6 +22,7 @@
   "files": [
     "bin/",
     "src/",
+    "scripts/postinstall.js",
     "README.md",
     "LICENSE"
   ],

package/scripts/postinstall.js

@@ -0,0 +1,33 @@
+/**
+ * The one line an install owes the user.
+ *
+ * `npm i -g vibeaudio` used to end in silence: nothing plays until hooks are
+ * installed or a command is wrapped, so someone who installed it and then went
+ * back to work heard nothing and concluded it was broken. This says what to
+ * run next, once, at the only moment the user is definitely looking.
+ *
+ * It must never fail an install. Anything thrown here is npm's problem to
+ * report and the user's to wonder about, so everything is wrapped and the exit
+ * code is always 0 - a greeting is not worth a failed install.
+ */
+try {
+  // Local installs are a dependency of something else; their user is not here
+  // and not the one who would run `vibe`. CI and Docker set this too.
+  // No isTTY check: npm pipes lifecycle output often enough that gating on it
+  // would mean the hint never lands for the people who need it. A global
+  // install is already the narrow case - a dependency install sets this false.
+  if (process.env.npm_config_global === "true") {
+    const c = (code, text) => `\x1b[${code}m${text}\x1b[0m`;
+    console.log(`
+${c("1;36", "🎧 VibeAudio installed.")} Two ways to start:
+
+  ${c("1", "vibe --install-hooks")}   ${c("90", "music follows your agent's thinking — best for Claude Code, Codex, Cursor…")}
+  ${c("1", "vibe npm test")}          ${c("90", "wrap any command that exits when it's done")}
+
+  ${c("90", "vibe            to pick a tool and a sound from a menu")}
+  ${c("90", "vibe --preview jazz   to hear one first")}
+`);
+  }
+} catch (e) {
+  // Deliberately silent: see above.
+}