# Companion Island

## Purpose

The Companion Island is Mastermind's only primary interaction surface. It keeps the assistant absent from the desktop until requested while making it available at a stable physical location.

It is inspired by the expansion behavior of Dynamic Island, but it is a Mastermind concept and must not be described as an Apple system feature.

## Placement

- The Companion Island belongs to the primary display only.
- Its activation area is centered on the display's top edge.
- On a notched display, the activation area follows the camera housing.
- On a display without a notch, the same area behaves as a virtual camera housing.
- Changing the primary display relocates the Companion Island.

## Interaction states

### Hidden

No Companion Island content is visible. Moving the pointer into the activation area begins the reveal transition.

### Revealed

A compact capsule grows from the camera area without taking keyboard focus. Leaving the activation region without clicking collapses it after a short grace period.

### Expanded

Clicking the revealed capsule expands it downward into an interactive panel and focuses text input. Expansion must feel spatially connected to the camera area rather than like an unrelated window appearing.

The expanded surface contains navigation for:

- Assistant;
- Assistant History;
- Sources;
- Local Provider;
- Context Graph and Context Receipts;
- Activity Log;
- Privacy, storage, export/import, and diagnostics.

Escape, an explicit close action, or clicking outside the panel returns it to Hidden. Long-running local work continues after collapse and is visible when the panel is reopened.

### Paused

Paused is a Collector condition, not a separate window mode. The user can still open the Companion Island, search existing context, and use Assistant History while all Collectors remain stopped.

## Menu Bar Item

The Menu Bar Item is visible whenever Mastermind runs. Its glyph does not change with capture state.

Its menu must expose:

- current state of every enabled Collector;
- permission and processing errors;
- Pause All or Resume All;
- Show Mastermind;
- Launch at Login state;
- Quit Mastermind.

Show Mastermind expands the Companion Island and is the fallback when pointer activation is unavailable. The MVP has no global hotkey.

## Focus and accessibility

- Hidden and Revealed do not steal focus.
- Expanded accepts keyboard focus and text input.
- Pointer activation must not create a dead strip that prevents access to the macOS menu bar.
- Animation respects Reduce Motion.
- The interface remains keyboard-navigable after it is expanded.
- Collector state and errors are conveyed with text, not color alone.

## Capture behavior

Mastermind excludes its own windows from the Screen Collector. It also requests exclusion from third-party capture where supported by macOS.

Capture exclusion is best effort. The UI must not promise that the Companion Island is invisible to every screen-sharing or recording application. Mastermind never hides its process or system permission indicators.

## Acceptance checks

- At launch, only the Menu Bar Item is visible.
- Hovering the primary display's camera area reveals the capsule.
- A notchless primary display gets the same top-center interaction.
- A click expands the panel and focuses text input.
- Show Mastermind works when hover activation cannot be used.
- Escape and click-away collapse the panel.
- Pause All does not prevent access to existing knowledge or history.
- The Companion Island is absent from Mastermind's own captured frames.
- Changing the primary display relocates the activation area.
