# Context Shelf — UX brief

Context Shelf gathers useful evidence from your Mac into **books** so you can carry understanding between AI conversations. A book holds one question, investigation, project, or decision and the clips that support it.

## Find your shelf

On notched displays, a 64 × 5 point dark indicator sits beneath the notch. Hover to reveal a compact rack of physical black book spines with silver-blue accents. Click a book to open it. The expanded book remains open while you work; use the collapse control to return to the quiet resting indicator. On displays without a notch, the shelf rests entirely in the menu bar and opens beneath the book icon, clamped to the screen edges. The keyboard shortcut opens it on the display containing the pointer. Explicitly opened shelves stay open until dismissed; hover-opened shelves close after the pointer leaves. Reduce Motion removes the reveal and book movement.

Click the menu-bar book icon to toggle the shelf. Right-click it for capture actions.

## Start a book

Choose **Create a book**, give it a meaningful title, and add evidence. To learn with sample content, choose **Try an example** from the empty shelf. The database example brings together a customer schema, query, results, and findings.

A useful first session:

1. Create “Investigating missing customer records.”
2. Copy the customer schema from its source and capture it.
3. Add a query and the unexpected result or error.
4. Open **Sources** and inspect each clip’s content and source metadata.
5. Choose **Build context**, review its draft, then **Edit** to record your accepted findings and next question.
6. Choose **Preview handoff**. Tailor the text, then use **Copy context** to start an AI conversation.
7. Capture a useful answer back into the same book and review it before your next handoff.

![The installed book view](assets/book.png)

## Read a book

The **Working context** and **Sources** tabs share one inspector size, keeping the source list on the left as you switch. Warm charcoal surfaces and a restrained selection highlight keep attention on the content. Prose uses proportional type with generous line spacing; explicitly identified code uses monospace.

In **Sources**, the source name and capture date appear beneath the title. **Open original** opens an available web source. **Copy excerpt** copies only the selected clip’s text; **Preview handoff** in Working context opens the editable outgoing context for the book.

Use **Command-F** to search sources by title, text, or source. With the source list focused, use **Up/Down arrows** to select a clip. **Command-N** opens **Paste text…**; **Add clip** also offers clipboard, selection, screenshot, and file capture.

In book sources and Unfiled, press **Delete** or **Fn-Delete** to remove the selected clip immediately. The next clip stays selected (or the previous one at the end). Each deletion requires a separate key press. Delete continues to edit text normally when search or an editor has focus.

## Capture from across your Mac

| Action | Shortcut |
| --- | --- |
| Open shelf | Control + Option + Space |
| Capture clipboard | Control + Option + C |
| Clip selected text | Control + Option + X |
| Capture screenshot | Control + Option + S |

Within a book, **Add clip** offers **Paste text…**, **Capture clipboard**, **Capture selection**, **Take screenshot**, and **Choose files…**. The menu-bar icon also offers **Add files…**.

File capture accepts up to 25 MB per file. Imported images retain the original attachment and receive local OCR for text extraction. Screenshot selection can be cancelled: no clip is added, and the shelf reports the cancellation.

Selected-text capture requires your Accessibility opt-in. If an app does not expose selected text, copy it and use clipboard capture. Screen capture requires your Screen Recording opt-in; after granting it in macOS, capture again. Neither permission is required merely to begin using clipboard capture.

## Check provenance and grouping

Clips retain capture time and available source information. Unknown clipboard origin is labeled **Clipboard**. The app does not invent a source app or URL. Add a URL when a precise source matters.

Repeated clipboard copies reuse an identical saved capture, including after restarting the app or filing the original into a book. Text and source must match exactly; image and file attachments must also have identical contents. Changed content remains a new capture. An explicit capture into another book is allowed. Automatic repeats stay quiet; a deliberate repeat confirms where the capture is already saved.

An explicitly selected book takes priority. Otherwise, automatic grouping compares distinctive terms and source hosts; ambiguous captures go to **Unfiled**. This is lexical matching, so unrelated projects sharing language can be confused and related excerpts using different words can be missed.

Review the destination notification after capture. Use **Undo** for a mistaken recent capture. In the source explorer, use **Move to book** or **Unfiled** to correct the destination. Deleting a book preserves its clips in Unfiled.

![The installed source explorer](assets/explorer.png)

## Build context and continue elsewhere

**Build context** prepares a working draft. On compatible Macs with Apple Foundation Models available, synthesis runs on-device. Otherwise, the app prepares labeled source excerpts. No remote model account is required.

Check the draft against original clips, then use **Edit** to write your own objective, findings, and open questions. Building again replaces the working draft; preserve important edits before requesting another synthesis.

**Preview handoff** lets you tailor the exact outgoing text. Both **Copy context** and **Export Markdown** from that preview use your edits. This is useful when a new conversation needs only part of a book.

For an entire book with its files, choose **Export book folder**. The app creates a new folder containing `context.md`, `book.json`, and `attachments/`, using relative attachment links. Transfer the whole folder to keep it portable. Markdown-only exports refer to local attachments and do not embed those files.

## Preferences

- **Suggest related books automatically** enables automatic grouping.
- **Capture copied text automatically** opts into clipboard collection. Leave it off when you want deliberate captures only.
- **Enable Accessibility** opens the permission path needed for selected-text capture.
- **Read the guide** opens the bundled user and developer documentation.

## Privacy and retention

Books are stored locally and can contain sensitive information. Review what you export. A receiving assistant or connected agent harness handles the content under its own rules.

Deleting a clip removes its record but currently retains its attachment bytes in the local collection; unused attachment cleanup is not implemented. Back up the full collection directory, including attachments, when preserving your work.

## For developers and agents

The bundled `shelf` executable and MCP stdio server use the same collection as the interface. Use `shelf help` or MCP tool discovery to inspect the current contract. Set `CONTEXT_SHELF_HOME` to a separate directory for test work. See the [technical field guide](index.html#agents) for commands, storage behavior, and integration examples.

## Verification scope

The installed shelf, books, source explorer, clipboard capture and routing, editable handoff with exact clipboard output, screenshot-file import with local OCR and original-image retention, and on-device synthesis were verified through computer use. The automated suite contains 26 passing tests: 6 capture-reader OCR/file tests, 12 core tests, and 8 CLI tests.

Global hotkey delivery has not been verified live through computer use. Selected-text and interactive screenshot capture remain unverified end to end behind the first-use Accessibility and Screen Recording permissions. Use their menu commands after granting the relevant permission to check these workflows on your Mac.