--- title: Wayfinding — the breadcrumb trail and back/forward arrows --- # Wayfinding — the breadcrumb trail and back/forward arrows ## What it is The desktop titlebar's **left cluster**, immediately after the `OMNISCIO` wordmark, carries two square arrow buttons and a location trail. Together they answer the two questions the desktop app could not answer before: *where am I*, and *how do I get back*. - **The trail** reads `Productivity › The Vault`, or deeper: `Developer Tools › Dev Pipeline › Auto-lander`. Every crumb except the last is a real link — clicking `Productivity` opens that group's landing page, clicking `Dev Pipeline` returns you to that panel's first tab. The last crumb is the page you are already on, so it is plain text and carries `aria-current="page"`. - **The arrows** are browser-style back and forward, bound to **`Ctrl+[`** and **`Ctrl+]`**. Whenever the control is shown they are always visible, greyed out when there is nowhere to go, the way a browser's are. On macOS the same binding renders as `Cmd+[` / `Cmd+]`, which is the native Mac browser shortcut, so no platform-specific code is needed. Both chords are declared in the keybindings registry rather than hardcoded, so **you can rebind them in Settings** and they appear in the `?` shortcuts overlay automatically. This is a **desktop-only** surface. The mobile UI has its own `MobileBreadcrumb` and its own back stack; the two never stack on top of each other. ## Where to find it It is not a page you open — it is a control drawn in the desktop titlebar's **left cluster**, immediately after the `OMNISCIO` wordmark, so it is always on screen. Its on/off is the titlebar widget list: right-click the title bar and toggle **Location Trail**, or open **Settings → Widgets**. ## How it behaves ### Turning it off It is a **header widget**, so you add or remove it exactly like the others: right-click the title bar and toggle **Location Trail**, or use **Settings → Widgets**. Both surfaces read the same list, so they can never disagree. It is shown out of the box. Two things worth knowing: - Removing it hides **both** the trail and the arrows — the whole control, not half of it. - **`Ctrl+[` and `Ctrl+]` keep working** while it is removed. Hiding the chrome is not the same as unbinding the keys, and the shortcuts already have their own home in **Settings → Keyboard** if you want them gone too. There is deliberately **no separate on/off setting** for it. The widget list is the one control; a second switch would be two places to change the same thing. ### Why the app needed it Omniscio's desktop shell is an Electron window, not a browser tab. There is **no router in it** — of the 145 files that import `react-router`, none is in the desktop shell — so there has never been anything for a browser Back to act on. Before this, the only way back from a screen was to find your way in the sidebar, and nothing on screen told you which group the current screen belonged to. Worth knowing if you are reading old audit output: three product-polish audit runs (March 2026) recorded desktop navigation as passing on the stated premise that *"browser back works"*. It never has. A fourth run recorded the correct answer — `Browser back: Not applicable (Electron app)` — so the audits contradicted each other, and the incorrect pass is the one that stuck. ### How "where am I" is worked out This is the part that surprises people, and it is worth understanding if the trail ever shows something you did not expect. **A location in Omniscio is two things, not one.** There are only 17 top-level views, and 14 of them are full-screen surfaces you rarely open. Almost everything you actually use — The Vault, Time Tracker, Team Chat, Dev Pipeline — is a **virtual project opened inside the dashboard**. So the app's real location is the view *plus* the active project, and, when a panel opts in, one or more levels below that. That is why the trail has up to three parts: | Where you are | Trail | |---|---| | A full-screen view | `Mind Map` | | A hub inside the dashboard | `Productivity › The Vault` | | A tab inside that hub | `Developer Tools › Dev Pipeline › Auto-lander` | | A plain folder project | `Projects › ` | | The dashboard with nothing open | arrows only, no trail | **The depth is not capped at three.** A panel that nests further can publish more levels and the trail grows to match. The group and panel names come from the same integration manifests the sidebar reads, so a crumb can never disagree with the sidebar row it corresponds to. ### Third-level crumbs are opt-in, per panel A panel's open tab lives in that component's own state, which the titlebar cannot see. So a panel publishes its position with one line, and the shell joins it on. **22 panels currently publish a third crumb:** Agent Messages, AI Coaching, API Keys, Bug Intake, ContextDock, Dev Pipeline, File Converter, Google Meet, Habits, Hooks, Marketplace, Meetings, Night Shift, Notification History, Overseers, Screen Capture, Settings, Statistics, Teams, Test Regime Monitor, Time Tracker, Voiceprint Studio. **Some panels deliberately do not**, and this is a design decision rather than an omission. A strip that toggles *which list the sidebar shows* — KMS's `Files | Sessions`, Tasks, Supermail, Flowchart, Workflows — is not a location, and naming it in the trail would tell you something confidently wrong. So would a meeting **filter** (Zoom), a mobile-only board switch (Jira, Linear), or tabs that live inside a dialog. A short trail is better than a wrong one. **Settings publishes its *section*, not its tab.** Its one tab strip is shared by 13 hub pages and knows only the inner tab, so publishing that would read `Settings › General` without saying which hub. The section is published instead, so the trail reads `System › Settings › Appearance` and names the page you are actually on. The label comes from the same list the settings nav renders, so a page's crumb and its nav row cannot drift apart. *Settings did not ship with the original feature.* When the breadcrumb first landed (`77fb828edb8`, 3 Sep 2026), Settings was the one panel deliberately left out — the trail read `System › Settings` on every one of its 13 pages and never named the page you were on. It was recorded as a known gap rather than skipped quietly, with the fix written into the reason: publish the section first. A later branch did exactly that, and deleted the exclusion in the same commit. The inner tab is still open — 13 one-line edits, one per hub — and is now the only part left. One known gap remains, recorded rather than quietly skipped: - **Marketplace Review**'s tabs describe the submission you have selected, so a crumb would name the facet without naming the submission. A guard test enforces this: any panel with a detectable tab strip must either publish it or appear in a list with a written reason. A new panel fails the build until its author picks one, so the coverage cannot silently rot. ### What the arrows remember Back and forward behave like a browser, not like "go up a level". From The Vault, Back returns to wherever you actually were before — the Daily Digest, the Inbox, whatever it was — not up to Productivity. **Three things deliberately do not enter the history:** - The **app tour** revealing a screen, so Back can never drop you into the middle of a tour. - The **post-onboarding landing**, so Back cannot walk you into setup. - The app's **boot restore**, which is not a navigation you performed. History is capped at 20 entries, and going somewhere new clears the forward stack — again, exactly as a browser does. ### Things you might notice - **The arrows are greyed on a fresh launch.** That is correct: nothing is behind you yet. They are still drawn, so you can see where they are. - **The trail truncates rather than pushing the toolbar around.** It is the one element in the titlebar allowed to give up width; a long screen name gets an ellipsis, and hovering shows the full path. - **`OMNISCIO` appears once.** The wordmark is the trail's implicit root, so the trail itself never repeats it. - **The group and panel names are English**, even in another language. Those come from the integration manifests, which are not translated; the view names themselves do translate. ### Not built (and why) - **Mouse back/forward buttons (X1/X2)** — Windows delivers these to the main process as an `app-command`, not as a renderer click, and the shell has no global mouse handling at all. It is a whole new input surface for a payoff limited to five-button mice. - **Reveal-in-sidebar for a plain folder project** — every sidebar group has a landing page, so this would apply to exactly one synthetic crumb. ## For agents Full invariants, the file-level sources of truth, and the safe-change checklist live in [wayfinding-breadcrumb-contract.md](../../.claude/memory/contracts/wayfinding-breadcrumb-contract.md). Read it before changing the resolver, the history store, or any panel's `usePanelBreadcrumb` call. ## Related Because the trail is built from the same manifests the sidebar reads, [Settings Drilldown Nav](settings-drilldown-nav.md) describes the panel-and-tab structure a crumb is naming. [Hub Jumper](hub-jumper.md) and [Quick Launch Modal](quick-launch-modal.md) are the two keyboard-first ways to move between the same places, and the arrow chords themselves are listed with everything else in [Keyboard Shortcuts](keyboard-shortcuts.md).