Header pins

Header pins are the shortcut icons that appear in the toolbar's left cluster. Each pin holds a frameset template — clicking it replaces the live singleton frameset with a fresh copy of that template. Pins give you one-click access to the views you reach for most often, and their order, labels, and icons are fully under your control.

Built-in pins vs user pins

Three built-in pins exist by default, in this order. Each applies a template to the singleton frameset:

Pin	Default label	Canonical route
Dashboard	Dashboard	`/dashboard`
Inbox	Inbox	`/`
Archives	Archives	`/archives`

Built-in pins back the app's canonical routes. Removing the Inbox pin from the header does not delete the Inbox frameset — it only hides the toolbar icon. You can always re-add a built-in pin from the management dialog.

User-created pins apply templates in the same way. Removing a pin removes its saved template, not workspace content. Built-in routes remain reachable after their toolbar pins are removed, including /dashboard. The default boot route remains Inbox.

At phone widths (≤640px)

On a phone-width viewport, the toolbar's left cluster becomes the scrollable header pin rail: a horizontally swipeable strip holding every leading-nav item — saved pins, the temp pin (when in draft mode), the New frameset button, and the gear icon — in the same order as on desktop. Every one of them stays reachable by swiping; nothing collapses behind an overflow menu at this width, and the active pin scrolls into view automatically when you switch to it.

The right side of the toolbar narrows to two controls: the notification bell and a kebab menu. The kebab holds everything else the desktop right cluster shows inline, including the command palette entry, and its trigger carries a small sync-status dot so you can see sync state at a glance without opening the menu.

Opening the management dialog

Click the gear icon on the left side of the toolbar header (the icon appears among the left-cluster pin icons). This opens the Manage header pins dialog where all create, edit, reorder, and remove operations live.

The dialog has two regions: a horizontal strip of pin tiles along the top (one larger icon-and-label tile per pin, plus a trailing Add pin tile), and a detail panel below it that describes whichever tile is currently selected. Opening the dialog auto-selects the first pin, so its detail panel is shown right away.

The command palette also has a "Manage header pins" entry bound to the same dialog.

A separate Header Pins group item in the command palette provides a quick navigation drill-down: selecting it lists every resolved header pin (default: Dashboard, Inbox, Archives), and selecting a pin navigates directly to it — without opening the management dialog. This is distinct from "Manage header pins", which opens the dialog for create, edit, reorder, and remove operations.

Adding a pin

Open the management dialog.
Click the Add pin tile (the dashed tile at the end of the icon strip).
The Add pin flow takes over the dialog body and walks you through up to three steps:
- Pick a provider — choose which view type the pin points to. A provider appears here if it satisfies any one of three criteria: it declares a non-empty layouts[] array (the layout-mode providers like Inbox or Archives), it ships a SettingsContent props form (it configures itself before pinning), or it has singletonScope: "none" (a self-contained provider that needs no layout or settings step — core.ai-assistant is the canonical example). The core.empty provider is always excluded.
- Pick a layout — for layouts[] providers, choose which layout the pin activates by default. Providers without layouts skip straight to the next step.
- Set label and icon — type a display label and pick an icon from the icon picker.
Click Save. The new pin appears as a tile at the end of the strip, is auto-selected (its detail panel opens), and is immediately visible in the toolbar.

Editing a pin (rename or change icon)

Open the management dialog.
Click the pin's tile in the strip to select it — its detail panel opens below.
Click Edit in the detail panel.
Update the label, the icon, or both.
Click Save.

The pin's backing frameset and its routing slug are not affected by an edit — only the display metadata changes.

Removing a pin

Open the management dialog.
Click the pin's tile to select it, then click Remove in its detail panel.
Read the confirmation message:
- For built-in pins: "The underlying view will stay available — only the header icon is removed."
- For user pins: "The pin's saved frameset will also be deleted. This cannot be undone."
Click Remove to confirm, or Cancel to go back.

Reordering pins

In the management dialog, grab a pin tile by its drag handle (the six-dot grip in the corner of the tile) and drag it left or right along the icon strip to the desired position. The strip reorders horizontally and the new order takes effect immediately in the toolbar. On a narrow (mobile) viewport the tiles wrap into a grid and reorder within that grid.

Missing-target tiles (see below) are not draggable — they stay in place until you remove them.

Visibility toggle

Select a pin's tile, and its detail panel shows a Show in header checkbox. Toggling a pin off hides its icon in the toolbar but keeps the pin in settings — the frameset and all its saved state remain intact, and the tile stays in the dialog (shown dimmed). Toggle it back on to restore the toolbar icon.

Toggling off is not the same as removing. Use the toggle when you want to temporarily declutter the toolbar without losing the frameset.

Routing and deep links

Each user pin gets a short URL of the form /p/<slug>. The slug is generated automatically when the pin is created — it is not user-editable and is never shown in the UI. The slug provides a stable deep-link that survives label and icon changes.

Built-in pins keep their canonical routes (/, /archives) regardless of any label changes.

Missing-target tiles

If the app cannot resolve a pin's backing frameset, provider, or layout at runtime, the pin appears as a missing-target tile (marked with a warning triangle) in the icon strip instead of a normal draggable tile. This can happen if a provider was unregistered or if settings data was manually edited.

Selecting a missing-target tile surfaces a remove-only detail panel: no layout preview and no edit or visibility controls, just a Remove button. Removing it cleans up the dangling reference from settings — the frameset is already gone, so only the pin entry is deleted.

Switching to a pin

Clicking a saved pin in the toolbar sets the active frameset to the pin's saved tree. If the live tree was already matching that saved frameset (no draft active), clicking the pin is a no-op — the toolbar icon stays highlighted and nothing changes.

If the live tree was in draft mode when you click a saved pin, the draft is discarded silently and the selected saved frameset is restored. The temp pin disappears and the clicked pin becomes highlighted.

Divergence and the temp pin

When divergence happens

Every live-tree change — resizing a panel divider, switching a frame's layout mode, or any other structural edit — is matched against all saved framesets. If the resulting tree matches a saved frameset, the corresponding pin becomes highlighted and the app stays in "saved" mode. If the tree does not match any saved frameset, the app enters draft mode.

Temp pin appearance

In draft mode, a temp pin appears with a LayoutGrid icon at the end of the left-cluster pin row — after all saved pins, before the divider and gear. The temp pin is visible when no saved pin matches the live frameset tree AND at least one saved pin exists. No saved pin is highlighted while the temp pin is present. The temp pin disappears as soon as the user saves the draft as a new pin or restores a saved pin.

Saving the draft as a new pin

Click the temp pin to open the Save current frameset as pin dialog. The dialog shows:

A layout preview of the live frameset tree.
A label field for the display name of the new pin.
An icon picker for the toolbar icon.
A Save button.

Click Save to promote the current live tree to a new saved pin. The temp pin disappears and the new pin becomes highlighted in the toolbar.

The command palette has an equivalent entry: "Save current frameset as pin".

Discarding the draft

Hold Cmd and click the temp pin to restore the previously-applied saved pin. The app rebuilds the singleton frameset from that pin's template (minting fresh frame ids) and the temp pin disappears.

This restore breadcrumb is session-only — it tracks only the last pin the user explicitly navigated to in the current session. Quitting and relaunching the app clears it. If no pin has been applied yet this session, Cmd+click is a no-op (a brief toast appears: "No previous pin to restore").

Alternatively, closing the extra frames that caused the divergence is a natural recovery path: once the live tree re-matches a saved pin's template, that pin highlights automatically and the temp pin disappears.

Restoring default content

If you want to reset a saved frameset's layout back to the way it looked when the app first launched (or when the frameset was created), open the Manage header pins dialog, click the edit button on the pin's row, and use the Reset to default layout option. This overwrites the frameset's stored tree with its original default tree.

For built-in framesets (Inbox, Archives), the default tree is the single-leaf layout the provider ships with.