## CHANGES

- Added context window warnings with one-click “Compact & Continue” compression 🚦
- Introduced per-tab input toggles for History, Read-only, and Thinking modes 🎛️
- Enabled configurable default toggle states for new AI tabs in Settings 🧩
- Added flexible send-key configuration for AI and terminal modes ⌨️
- Shipped Image Carousel for managing multi-image attachments fast 🖼️
- Expanded Git docs with built-in log viewer and commit navigation 🌿
- Documented syntax-highlighted diff viewer with side-by-side comparisons 🔍
- Upgraded worktree workflows: manage, watch changes, PRs, safe removal 🧰
- Added comprehensive AI tab shortcut table for all toggle actions 🗂️
- Documented shortcut remapping flow, conflict behavior, and restoration tips 🧠

docs/configuration.md

@@ -16,7 +16,7 @@ Maestro can sync settings, sessions, and groups across multiple devices by stori
 
 **Setup:**
 
-1. Open **Settings** (`Cmd+,`) → **General** tab
+1. Open **Settings** (`Cmd+,` / `Ctrl+,`) → **General** tab
 2. Scroll to **Storage Location**
 3. Click **Choose Folder...** and select a synced folder:
    - **iCloud Drive**: `~/Library/Mobile Documents/com~apple~CloudDocs/Maestro`

docs/context-management.md

@@ -26,7 +26,7 @@ Right-click any tab to access the full range of context management options:
 Export any tab conversation as a self-contained HTML file:
 
 1. Right-click the tab → **Context: Copy to Clipboard**
-2. Or use **Command Palette** (`Cmd+K`) → "Export tab to HTML"
+2. Or use **Command Palette** (`Cmd+K` / `Ctrl+K`) → "Export tab to HTML"
 
 The exported HTML file includes:
 - **Full conversation history** with all messages
@@ -45,6 +45,44 @@ Context management lets you combine or transfer conversation history between ses
 - **Merge sessions** — Combine context from multiple conversations into one
 - **Transfer to other agents** — Send your context to a different AI agent (e.g., Claude Code → Codex)
 
+## Context Window Warnings
+
+As your conversation grows, Maestro monitors context window usage and displays warnings when you're approaching limits.
+
+![Context Warning Banner](./screenshots/context-warnings.png)
+
+The warning banner appears below the input box showing:
+- Current context usage percentage
+- **Compact & Continue** button for one-click context compression
+
+### Why Context Usage Matters
+
+**Operating near context limits degrades AI performance.** When context reaches ~80% capacity or higher:
+
+- The AI loses access to earlier parts of your conversation
+- Important decisions, code changes, and context get pushed out
+- Response quality drops as the model struggles to maintain coherence
+- You may experience more hallucinations and forgotten instructions
+
+For best results, **compact your context before reaching 60-70% usage** — don't wait for the red warning.
+
+### Configuring Warnings
+
+Customize warning thresholds in **Settings** (`Cmd+,` / `Ctrl+,`) → **General** → **Context Window Warnings**:
+
+![Context Warning Configuration](./screenshots/context-warnings-config.png)
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| **Show context consumption warnings** | Enabled | Toggle warning banners on/off |
+| **Yellow warning threshold** | 60% | Early warning — good time to consider compacting |
+| **Red warning threshold** | 80% | Critical — compact immediately to avoid degradation |
+
+**Recommended thresholds:**
+- Set yellow to **50-60%** if you prefer earlier warnings
+- Set red to **70-80%** — going higher risks quality degradation
+- Lower both thresholds if you frequently work on complex tasks that require the AI to remember many details
+
 ## Compact & Continue
 
 When your conversation approaches context limits, you can compress it while preserving essential information:

docs/features.md

@@ -16,8 +16,8 @@ icon: sparkles
 
 ## Core Features
 
-- 🔄 **Dual-Mode Sessions** - Each agent has both an AI Terminal and Command Terminal. Switch seamlessly between AI conversation and shell commands with `Cmd+J`.
-- ⌨️ **[Keyboard-First Design](./keyboard-shortcuts)** - Full keyboard control with customizable shortcuts and [mastery tracking](./achievements) that rewards you for leveling up. `Cmd+K` quick actions, rapid agent switching, and focus management designed for flow state.
+- 🔄 **Dual-Mode Sessions** - Each agent has both an AI Terminal and Command Terminal. Switch seamlessly between AI conversation and shell commands with `Cmd+J` / `Ctrl+J`.
+- ⌨️ **[Keyboard-First Design](./keyboard-shortcuts)** - Full keyboard control with customizable shortcuts and [mastery tracking](./achievements) that rewards you for leveling up. `Cmd+K` / `Ctrl+K` quick actions, rapid agent switching, and focus management designed for flow state.
 - 📋 **Session Discovery** - Automatically discovers and imports all Claude Code sessions, including conversations from before Maestro was installed. Browse, search, star, rename, and resume any session.
 - 🔀 **Git Integration** - Automatic repo detection, branch display, diff viewer, commit logs, and git-aware file completion. Work with git without leaving the app.
 - 📁 **[File Explorer](./general-usage)** - Browse project files with syntax highlighting, markdown preview, and image viewing. Reference files in prompts with `@` mentions.

docs/general-usage.md

@@ -52,6 +52,61 @@ The Prompt Composer provides:
 
 When you're done editing, click **Send** or press the displayed shortcut to send your message. The composer closes automatically and your prompt is sent to the AI.
 
+## Input Toggles
+
+The AI input box includes three toggle buttons that control session behavior:
+
+![Input Toggles](./screenshots/input-toggles.png)
+
+| Toggle | Shortcut | Description |
+|--------|----------|-------------|
+| **History** | `Cmd+S` / `Ctrl+S` | Save a synopsis of each completion to the [History panel](./history) |
+| **Read-only** | `Cmd+R` / `Ctrl+R` | Enable plan/read-only mode — AI can read but not modify files |
+| **Thinking** | `Cmd+Shift+K` / `Ctrl+Shift+K` | Show streaming thinking/reasoning as the AI works |
+
+**Per-tab persistence:** Each toggle state is saved per tab. If you enable Thinking on one tab, it stays enabled for that tab even when you switch away and back.
+
+### Configuring Defaults
+
+Set the default state for new tabs in **Settings** (`Cmd+,` / `Ctrl+,`) → **General**:
+
+![Input Toggle Defaults](./screenshots/input-toggles-defaults.png)
+
+| Setting | Description |
+|---------|-------------|
+| **Enable "History" by default** | New tabs save synopses to History automatically |
+| **Enable "Thinking" by default** | New tabs show thinking/reasoning content by default |
+
+### Send Key Configuration
+
+Configure how messages are sent in each mode:
+
+| Mode | Options | Description |
+|------|---------|-------------|
+| **AI Interaction Mode** | `Enter` or `Cmd+Enter` | Choose your preferred send key for AI conversations |
+| **Terminal Mode** | `Enter` or `Cmd+Enter` | Choose your preferred send key for shell commands |
+
+- When set to `Cmd+Enter` / `Ctrl+Enter`, pressing `Enter` alone creates a new line (for multi-line input)
+- When set to `Enter`, use `Shift+Enter` for new lines
+- The current send key is displayed in the input box (e.g., "⌘ + Enter")
+- **Per-tab override:** Click the send key indicator in the input box to toggle between modes for that tab
+
+## Image Carousel
+
+When working with image attachments, use the **Image Carousel** to view, manage, and remove images.
+
+**To open the Image Carousel:**
+- Press `Cmd+Y` / `Ctrl+Y`, or
+- Click the image icon in the input box when images are attached
+
+**Carousel controls:**
+- **Arrow keys** — Navigate between images
+- **Delete** or **Backspace** — Remove the currently selected image
+- **Click the X** — Remove an image by clicking its remove button
+- **Esc** — Close the carousel
+
+Images can be attached via drag-and-drop, paste, or the attachment button. The carousel shows all images queued for the current message.
+
 ## Output Filtering
 
 Search and filter AI output with include/exclude modes, regex support, and per-response local filters.
@@ -64,6 +119,6 @@ The command interpreter can be focused for a clean, terminal-only experience whe
 
 ## Session Management
 
-Browse, star, rename, and resume past sessions. The Session Explorer (`Cmd+Shift+L`) shows all conversations for an agent with search, filtering, and quick actions.
+Browse, star, rename, and resume past sessions. The Session Explorer (`Cmd+Shift+L` / `Ctrl+Shift+L`) shows all conversations for an agent with search, filtering, and quick actions.
 
 ![Session tracking](./screenshots/session-tracking.png)

docs/git-worktrees.md

@@ -1,40 +1,90 @@
 ---
-title: Git Worktrees
-description: Run AI agents in parallel on isolated branches with Git worktree sub-agents.
+title: Git and Worktrees
+description: Browse commit history, view diffs, and run AI agents in parallel on isolated branches with Git worktree sub-agents.
 icon: git-branch
 ---
 
-Git worktrees enable true parallel development by letting you run multiple AI agents on separate branches simultaneously. Each worktree operates in its own isolated directory, so there's no risk of conflicts between parallel work streams.
+Maestro integrates deeply with Git, providing visual tools for exploring repository history and enabling parallel development with worktree sub-agents.
 
-Maestro's git integration includes built-in diff viewing and commit log browsing:
+## Git Log Viewer
+
+Browse your commit history directly in Maestro:
 
 ![Git logs](./screenshots/git-logs.png)
+
+The log viewer shows:
+- **Commit history** with messages, authors, and timestamps
+- **Branch visualization** with merge points
+- **Quick navigation** to any commit
+
+Access via **Command Palette** (`Cmd+K` / `Ctrl+K`) → "Git Log" or the git menu in the Left Bar.
+
+## Diff Viewer
+
+Review file changes with syntax-highlighted diffs:
+
 ![Git diff](./screenshots/git-diff.png)
 
-## Creating a Worktree Sub-Agent
+The diff viewer displays:
+- **Side-by-side comparison** of file versions
+- **Syntax highlighting** matched to file type
+- **Line-by-line changes** with additions and deletions clearly marked
 
-1. In the agent list (left sidebar), hover over an agent in a git repository
-2. Click the **git branch indicator** (shows current branch name)
-3. In the overlay menu, click **"Create Worktree Sub-Agent"**
-4. Configure the worktree:
-   - **Worktree Directory** — Base folder where worktrees are created
-   - **Branch Name** — Name for the new branch (becomes the subdirectory name)
-   - **Create PR on Completion** — Auto-open a pull request when done
-   - **Target Branch** — Base branch for the PR (defaults to main/master)
+Access diffs from the git log viewer by clicking any commit, or use **Command Palette** → "Git Diff".
 
-## How Worktree Agents Work
+---
 
-- **Nested Display** — Worktree sub-agents appear indented under their parent agent in the left sidebar
-- **Branch Icon** — A git branch icon indicates worktree agents
+## Git Worktrees
+
+Git worktrees enable true parallel development by letting you run multiple AI agents on separate branches simultaneously. Each worktree operates in its own isolated directory, so there's no risk of conflicts between parallel work streams.
+
+### Managing Worktrees
+
+Worktree sub-agents appear nested under their parent agent in the Left Bar:
+
+![Worktree list](./screenshots/git-worktree-list.png)
+
+- **Nested Display** — Worktree sub-agents appear indented under their parent agent
+- **Branch Icon** — A green checkmark indicates the active worktree
 - **Collapse/Expand** — Click the chevron on a parent agent to show/hide its worktree children
 - **Independent Operation** — Each worktree agent has its own working directory, conversation history, and state
 
-## Creating Pull Requests
+### Creating a Worktree Sub-Agent
+
+1. In the agent list (Left Bar), hover over an agent in a git repository
+2. Click the **git branch indicator** (shows current branch name)
+3. In the overlay menu, click **"Create Worktree Sub-Agent"**
+4. Configure the worktree:
+
+![Worktree configuration](./screenshots/git-worktree-configuration.png)
+
+| Option | Description |
+|--------|-------------|
+| **Worktree Directory** | Base folder where worktrees are created (should be outside the main repo) |
+| **Watch for Changes** | Monitor the worktree for file system changes |
+| **Create New Worktree** | Branch name for the new worktree (becomes the subdirectory name) |
+
+**Tip:** Configure the worktree directory to be outside your main repository (e.g., `~/Projects/Maestro-WorkTrees/`). This keeps worktrees organized and prevents them from appearing in your main repo's file tree.
+
+### Worktree Actions
+
+Right-click any worktree sub-agent to access management options:
+
+![Worktree right-click menu](./screenshots/git-worktree-right-click.png)
+
+| Action | Description |
+|--------|-------------|
+| **Rename** | Change the display name of the worktree agent |
+| **Edit Agent...** | Modify agent configuration |
+| **Create Pull Request** | Open a PR from this worktree's branch |
+| **Remove Worktree** | Delete the worktree agent (see below) |
+
+### Creating Pull Requests
 
 When you're done with work in a worktree:
 
 1. **Right-click** the worktree agent → **Create Pull Request**, or
-2. Press **Cmd+K** with the worktree active → search "Create Pull Request"
+2. Press `Cmd+K` / `Ctrl+K` with the worktree active → search "Create Pull Request"
 
 The PR modal shows:
 - Source branch (your worktree branch)
@@ -43,6 +93,19 @@ The PR modal shows:
 
 **Requirements:** GitHub CLI (`gh`) must be installed and authenticated. Maestro will detect if it's missing and show installation instructions.
 
+### Removing Worktrees
+
+When removing a worktree, you have two options:
+
+![Remove worktree confirmation](./screenshots/git-worktree-remove.png)
+
+| Option | What It Does |
+|--------|--------------|
+| **Remove** | Removes the sub-agent from Maestro but keeps the git worktree directory on disk |
+| **Remove and Delete** | Removes the sub-agent AND permanently deletes the worktree directory from disk |
+
+The confirmation dialog shows the full path to the worktree directory so you know exactly what will be affected.
+
 ## Use Cases
 
 | Scenario | How Worktrees Help |
@@ -55,5 +118,6 @@ The PR modal shows:
 ## Tips
 
 - **Name branches descriptively** — The branch name becomes the worktree directory name
-- **Use a dedicated worktree folder** — Keep all worktrees in one place (e.g., `~/worktrees/`)
-- **Clean up when done** — Delete worktree agents after merging PRs to avoid clutter
+- **Use a dedicated worktree folder** — Keep all worktrees in one place outside the main repo
+- **Clean up when done** — Remove worktree agents after merging PRs to avoid clutter
+- **Watch for Changes** — Enable file watching to keep the file tree in sync with worktree activity

docs/keyboard-shortcuts.md

@@ -41,6 +41,19 @@ The command palette is your gateway to nearly every action in Maestro. Press `Cm
 | Toggle Markdown Raw/Preview | `Cmd+E` | `Ctrl+E` |
 | Insert Checkbox (Auto Run) | `Cmd+L` | `Ctrl+L` |
 
+## AI Tab Shortcuts
+
+These shortcuts work in AI Terminal mode and affect the current tab:
+
+| Action | macOS | Windows/Linux |
+|--------|-------|---------------|
+| Toggle History | `Cmd+S` | `Ctrl+S` |
+| Toggle Read-Only Mode | `Cmd+R` | `Ctrl+R` |
+| Toggle Show Thinking | `Cmd+Shift+K` | `Ctrl+Shift+K` |
+| Open Image Carousel | `Cmd+Y` | `Ctrl+Y` |
+
+Toggle states are saved per-tab. See [Input Toggles](./general-usage#input-toggles) for details on configuring defaults.
+
 ## Input & Output
 
 | Action | Key |
@@ -111,20 +124,42 @@ In AI mode, use `@` to reference files in your prompts:
 | Scroll | `Up/Down Arrow` | `Up/Down Arrow` |
 | Close | `Esc` | `Esc` |
 
-*Most shortcuts are customizable in Settings > Shortcuts*
+## Customizing Shortcuts
+
+Most shortcuts can be remapped to fit your workflow:
+
+1. Open **Settings** (`Cmd+,` / `Ctrl+,`) → **Shortcuts** tab
+2. Find the action you want to remap
+3. Click the current key binding (shows the shortcut like `⌘ K` or `Ctrl+K`)
+4. Press your desired key combination
+5. The new binding is saved immediately
+
+**Tips:**
+- Press `Esc` while recording to cancel without changing the shortcut
+- Modifier keys alone (Cmd, Ctrl, Alt, Shift) won't register — you need a final key
+- Some shortcuts are fixed and cannot be remapped (like `Esc` to close modals)
+- Conflicting shortcuts will override the previous binding
+
+**Resetting shortcuts:** There's currently no "reset to default" button — if you need to restore defaults, you can find the original bindings in this documentation or delete the shortcuts from your settings file.
 
 ## Keyboard Mastery
 
-Maestro tracks your keyboard shortcut usage and rewards you for becoming a power user. As you use more shortcuts, you'll level up through the mastery ranks:
+Maestro tracks your keyboard shortcut usage and rewards you for becoming a power user. As you discover and use more shortcuts, you'll level up through 5 mastery levels:
 
-| Level | Threshold | Name | Description |
-|-------|-----------|------|-------------|
-| 0 | 0% | **Beginner** | Just starting out |
-| 1 | 25% | **Student** | Learning the basics |
-| 2 | 50% | **Performer** | Getting comfortable |
-| 3 | 75% | **Virtuoso** | Almost there |
-| 4 | 100% | **Keyboard Maestro** | Complete mastery |
+| Level | Title | Shortcuts Used |
+|:-----:|-------|----------------|
+| 0 | **Novice** | 0-19% |
+| 1 | **Apprentice** | 20-39% |
+| 2 | **Journeyman** | 40-59% |
+| 3 | **Expert** | 60-79% |
+| 4 | **Master** | 80-100% |
 
-When you reach a new level, you'll see a celebration with confetti. Your progress is tracked in the Shortcuts Help modal (`Cmd+/` or `Ctrl+/`), which shows your current mastery percentage and hints at shortcuts you haven't tried yet.
+**Tracking your progress:**
+- Your current mastery level is shown in the **status bar** at the bottom of the window
+- Hover over the keyboard icon to see which shortcuts you've used and which remain to be discovered
+- Open the **Shortcuts Help** modal (`Cmd+/` / `Ctrl+/`) to see your mastery percentage and get hints
+- When you reach a new level, you'll see a celebration with confetti
 
 **Why keyboard shortcuts matter:** Using shortcuts keeps you in flow state, reduces context switching, and dramatically speeds up your workflow. Maestro is designed for keyboard-first operation — the less you reach for the mouse, the faster you'll work.
+
+Keyboard Mastery is separate from [Conductor Ranks](./achievements), which track cumulative Auto Run time. Both systems reward you for mastering different aspects of Maestro.