docs: refresh readme for onboarding and notifications

1 files changed, 33 insertions, 22 deletions

diff --git a/README.md b/README.md
index 86962535..2b67d338 100644
--- a/README.md
+++ b/README.md
@@ -12,7 +12,9 @@
 
 ---
 
-herdr is a terminal workspace manager for AI coding agents. it runs inside your existing terminal — ghostty, alacritty, kitty, wezterm, even inside tmux. a single rust binary that gives you workspaces, tiled panes, and intelligent agent state detection.
+herdr is a terminal workspace manager for AI coding agents. it runs inside your existing terminal: ghostty, alacritty, kitty, wezterm, even inside tmux. a single rust binary that gives you workspaces, tiled panes, intelligent agent state detection, and optional notification alerts.
+
+it stays terminal-native without forcing a keyboard-only workflow: use prefix keys when you want, click and drag when you don't.
 
 you keep your terminal. herdr keeps track of your agents.
 
@@ -22,24 +24,28 @@ you keep your terminal. herdr keeps track of your agents.
 
 ## philosophy
 
-every tool in this space is building more. desktop apps, electron wrappers, web dashboards — all trying to replace your terminal with their own environment.
+every tool in this space is building more. desktop apps, electron wrappers, web dashboards, all trying to replace your terminal with their own environment.
 
 herdr takes the opposite approach. it's a tool that lives where you already work. it sits alongside tmux, inside your terminal emulator, part of your existing workflow. it does one thing well: lets you run multiple coding agents in parallel and know when they need you.
 
-the terminal is already a great environment for coding agents. what's been missing is awareness — seeing at a glance which agent is idle, which is working, and which needs your input. herdr adds that layer.
+the terminal is already a great environment for coding agents. what's been missing is awareness: seeing at a glance which agent is idle, which is working, and which needs your input. herdr adds that layer.
+
+herdr also keeps workspace creation lightweight. a workspace is a terminal context, not a preconfigured project artifact. create one and it opens immediately; herdr labels it from your current repo or folder. you can rename it later, but that's an override, not a prerequisite.
+
+it also treats mouse support as a first-class interaction model, not an afterthought. click the sidebar to switch workspaces, drag pane borders to resize, scroll panes, and use the keyboard whenever it's faster.
 
 ## how it works
 
-herdr embeds real terminal emulators using PTY and vt100 parsing. each pane is a full terminal — your shell, your agent, your tools, exactly as they'd run anywhere else.
+herdr embeds real terminal emulators using PTY and vt100 parsing. each pane is a full terminal: your shell, your agent, your tools, exactly as they'd run anywhere else.
 
 the sidebar shows your workspaces. each workspace can have multiple tiled panes. the agent detection system reads terminal output in real time and determines what state each agent is in:
 
-- **●** red — agent is waiting for your input
-- **●** yellow — agent is working
-- **●** blue — agent finished (you haven't looked yet)
-- **○** green — agent is idle, you've seen it
+- **●** red: agent is waiting for your input
+- **●** yellow: agent is working
+- **●** blue: agent finished (you haven't looked yet)
+- **○** green: agent is idle, you've seen it
 
-when an agent finishes work in a background workspace, its dot turns blue. you see it at a glance and switch over. it just reads the terminal.
+when an agent finishes work in a background workspace, its dot turns blue. you see it at a glance and switch over. if you want more interruption, herdr can also play sounds or show top-right toast alerts for background events.
 
 ## supported agents
 
@@ -51,7 +57,7 @@ herdr detects agent state by identifying the foreground process and reading term
 | [claude code](https://docs.anthropic.com/en/docs/claude-code) | ✓ | ✓ | ✓ |
 | [codex](https://github.com/openai/codex) | ✓ | ✓ | ✓ |
 | [droid](https://factory.ai) | ✓ | ✓ | ✓ |
-| [amp](https://ampcode.com) | ✓ | ✓ | — |
+| [amp](https://ampcode.com) | ✓ | ✓ | - |
 | [opencode](https://github.com/anomalyco/opencode) | ✓ | ✓ | ✓ |
 
 detection heuristics also exist for these agents but haven't been fully tested yet. if you use them and run into issues, please [open an issue](https://github.com/ogulcancelik/herdr/issues):
@@ -62,7 +68,7 @@ detection heuristics also exist for these agents but haven't been fully tested y
 - [kimi](https://kimi.ai)
 - [github copilot cli](https://cli.github.com)
 
-for any other CLI agent, herdr still works as a workspace manager — you get workspaces, panes, and tiling. a hook system for custom agent state reporting is coming soon.
+for any other CLI agent, herdr still works as a workspace manager. you still get workspaces, panes, and tiling. a hook system for custom agent state reporting is coming soon.
 
 ## install
 
@@ -76,7 +82,7 @@ requirements: linux or macos.
 
 ### update
 
-herdr checks for updates automatically in the background. when a new version is ready, you'll see a notification in the UI — just restart to apply. you can also update manually:
+herdr checks for updates automatically in the background. when a new version is ready, you'll see a notification in the UI. just restart to apply. you can also update manually:
 
 ```bash
 herdr update
@@ -90,7 +96,9 @@ launch herdr:
 herdr
 ```
 
-herdr starts in **navigate mode**. press `n` to create your first workspace. it opens immediately as a new terminal context, and the workspace label is derived from its path/repo.
+on first run, herdr opens a short onboarding flow so you can choose your notification style. after that, if a session is restored you'll land in terminal mode; otherwise you'll start in **navigate mode**.
+
+press `n` to create your first workspace. it opens immediately as a new terminal context, using an automatic label based on your current repo or folder.
 
 press `ctrl+b` (the prefix key) to switch back to navigate mode. from there you can manage workspaces and panes.
 
@@ -120,6 +128,8 @@ full keybinding and config reference: [`CONFIGURATION.md`](./CONFIGURATION.md)
 
 ### mouse
 
+mouse support is built in. herdr is not keyboard-only.
+
 - click a workspace in the sidebar to switch
 - click a pane to focus it
 - drag split borders to resize
@@ -132,7 +142,7 @@ text copy uses OSC 52, so it depends on your terminal's clipboard support.
 
 ### terminal mode
 
-you're in a real terminal. everything works — your shell, vim, htop, ssh, anything. press the prefix key (`ctrl+b`) to go back to navigate mode.
+you're in a real terminal. everything works: your shell, vim, htop, ssh, anything. press the prefix key (`ctrl+b`) to go back to navigate mode.
 
 ## configuration
 
@@ -144,7 +154,7 @@ print the full default config with:
 herdr --default-config
 ```
 
-for all keybindings, UI options, sound settings, and environment variables, see [`CONFIGURATION.md`](./CONFIGURATION.md).
+for all keybindings, onboarding, notification, sound, UI options, and environment variables, see [`CONFIGURATION.md`](./CONFIGURATION.md).
 
 ## session persistence
 
@@ -162,19 +172,20 @@ herdr doesn't require hooks or agent-side configuration. detection works by:
 
 this means detection works with any supported agent, installed any way, with zero setup. if it runs in a terminal, herdr can see it.
 
-the heuristics are pattern-matched against each agent's actual terminal output — prompt boxes, spinners, "waiting for input" messages, tool execution indicators. detection runs on a separate async task per pane, polled every 300-500ms, decoupled from terminal rendering.
+the heuristics are pattern-matched against each agent's actual terminal output: prompt boxes, spinners, "waiting for input" messages, tool execution indicators. detection runs on a separate async task per pane, polled every 300-500ms, decoupled from terminal rendering.
 
 ## what's coming
 
-- **notification hooks** — a socket API so any agent or script can report its state to herdr. for agents without built-in detection, wire up a simple hook.
-- **native notifications** — OS-level notifications when an agent needs attention and herdr isn't in focus.
-- **agent API** — `herdr create`, `herdr split`, `herdr send` — so agents and scripts can manage herdr workspaces programmatically.
+- **notification hooks**: a socket API so any agent or script can report its state to herdr. for agents without built-in detection, wire up a simple hook.
+- **in-app preferences**: rerun onboarding and adjust things like sound and toast notifications without editing config by hand.
+- **native notifications**: OS-level notifications when an agent needs attention and herdr isn't in focus.
+- **agent API**: `herdr create`, `herdr split`, `herdr send`, so agents and scripts can manage herdr workspaces programmatically.
 
 ## built with agents
 
-i had never written rust before starting this project. herdr was built almost entirely through AI coding agents — the same ones it's designed to manage. i supervised the architecture and specs, agents wrote the code.
+i had never written rust before starting this project. herdr was built almost entirely through AI coding agents, the same ones it's designed to manage. i supervised the architecture and specs, agents wrote the code.
 
-this is a proof of concept in more ways than one. it's a functional tool, but it's also a statement about what's possible right now. if you can build a terminal multiplexer in a language you don't know, by directing the same agents the tool is built for — that says something about where we are.
+this is a proof of concept in more ways than one. it's a functional tool, but it's also a statement about what's possible right now. if you can build a terminal multiplexer in a language you don't know, by directing the same agents the tool is built for, that says something about where we are.
 
 there will be rough edges. if you hit one, [open an issue](https://github.com/ogulcancelik/herdr/issues). that's why it's open source.
 
@@ -208,4 +219,4 @@ just test-all           # both
 
 ## license
 
-AGPL-3.0 — free to use, modify, and distribute. if you distribute a modified version, you must open-source your changes under the same license.
+AGPL-3.0: free to use, modify, and distribute. if you distribute a modified version, you must open-source your changes under the same license.