--- title: Help & Docs Panel (in-app docs site) --- # Help & Docs Panel (in-app docs site) ## What it is A built-in help browser that loads the public Omniscio documentation site (`https://docs.omniscio.com`) inside an Electron `` without leaving the app. It's a full mini-browser — back / forward / home buttons, a title bar that mirrors the current section heading, and an **Open in browser** escape hatch — so you can read docs alongside your sessions instead of context-switching to Chrome. Originally external links in Omniscio kicked you to your default browser; the panel keeps reading flow inside Omniscio for everything documented on the help site. The panel is also the destination of every "?" / Help affordance in the toolbar and is the surface that other Omniscio features deep-link to when they want to show feature-specific docs (e.g. an empty state's "Learn more" link). ## Where to find it ### How to use it 1. **Open it.** Three entry points, all equivalent: - **Toolbar Help icon** — the `?` (HelpCircle) button in the toolbar's overflow row labeled **Help & Docs**. - **Keyboard shortcut** — `Ctrl+Shift+/` (rebindable at Settings → Keyboard Shortcuts → "Open Help"). - **Programmatic** — other features fire the `open-help-panel` window event to toggle it on. 2. **Read.** The webview loads the Omniscio docs site. Section headings show in the panel's title bar (extracted from the page's `.section.active h1`). The loading indicator is a thin accent bar across the top of the body while pages fetch. 3. **Navigate.** Standard browser nav inside the embedded page works as you'd expect — click any link, use the back ⟵ and forward ⟶ arrows in the panel header, or click the **home** icon to jump back to the docs landing page. The back/forward arrows are disabled when there's no history in that direction. 4. **Open in your real browser.** Click **Browser** in the header (link-out icon) to open the page you're viewing in your OS default browser — useful for sharing a docs URL, opening multiple help tabs, or using the browser's find-in-page if you need more than what the webview offers. 5. **External links handled cleanly.** If a link inside the docs site points to an external host (GitHub, external tools, etc.), Omniscio intercepts the `new-window` event and opens it via your OS default browser instead of spawning a separate webview window. The help panel itself stays on the docs site. 6. **Close.** Click the **×** in the panel header, or press `Ctrl+Shift+/` again to toggle back to the dashboard. ## How it behaves ### How it works **Component.** A single React component at [src/renderer/src/features/help/HelpPanel.tsx](/src/renderer/src/features/help/HelpPanel.tsx) wraps an Electron `` tag and a 44px (h-11) header bar with the back / forward / home / Browser / close buttons. The webview's `src` is `HELP_SITE_URL` plus an optional `#
` hash for deep-linking. `HELP_SITE_URL` is NOT a pinned literal — it is `DOCS_SITE_BASE`, the shared single source ([src/shared/docs-site-base.ts](/src/shared/docs-site-base.ts), `DEFAULT_DOCS_SITE_BASE = 'https://docs.omniscio.com'`, repointable per-seam via `RENDERER_VITE_HELP_SITE_URL`). Read the constant, never hard-code the host. **Lifecycle wiring.** [src/renderer/src/App.tsx](/src/renderer/src/App.tsx) lazy-loads the panel (`React.lazy()`) so the docs webview infrastructure isn't paid for until you actually open it. App.tsx tracks `currentView === 'help'` and toggles to/from `'dashboard'` when the `open-help-panel` window event fires. The keyboard handler at [src/renderer/src/hooks/useKeyboardShortcuts.ts](/src/renderer/src/hooks/useKeyboardShortcuts.ts) dispatches that event for the `openHelp` action, defined at [src/shared/keybindings.ts](/src/shared/keybindings.ts) with default `Ctrl+Shift+/`. **Title sync.** Whenever the embedded page finishes loading (`did-stop-loading`), Omniscio runs `document.querySelector('.section.active h1')?.textContent || 'Help'` inside the webview via `executeJavaScript` and writes the result into the panel's title bar. The docs site's CSS toggles the `.section.active` class on whichever anchored section is currently visible, so the title reflects what you're reading rather than the page's HTML ``. **Deep-linking from other features.** Features elsewhere in Omniscio fire `open-help-panel` with `{ ensureOpen: true, section }`. If the panel is already mounted, its `window.__helpPanelNavigate` handle (registered while mounted, removed on unmount) navigates the webview to `HELP_SITE_URL/#<section>` — a hash URL the docs site handles via its guarded `hashchange` listener whether or not the site's JS has finished loading. If the panel is NOT mounted yet, the section is staged in `help-panel-pending-section.ts` (a one-shot read-and-clear handoff) and consumed at mount into the webview's initial `#<section>` URL, so the deep link never races the panel or the site load. Only section ids that actually exist on the docs site are deep-linked (see `help-site-section-ids.ts`); the site itself also ignores an unknown hash rather than blanking the page. **Webview enablement requirement.** Embedding any `<webview>` tag requires `webPreferences.webviewTag: true` on the BrowserWindow, which in turn forces `sandbox: false`. This is a known and accepted security trade-off (also needed by RepoGuard, the email viewer, and other plugin UIs). It is recorded as accepted debt **L10-F01** in [g8-electron-sandbox-plugin-trust-postmortem.md](/.claude/memory/postmortems/g8-electron-sandbox-plugin-trust-postmortem.md), and the compensating control is documented in [electron-fuses-contract.md](/.claude/memory/contracts/electron-fuses-contract.md) — the main window cannot be sandboxed, so Electron fuses are the available defense-in-depth. Windows that do NOT host a webview stay fully sandboxed (the detached-session window, the OAuth popup); see [ai-browser-contract.md](/.claude/memory/contracts/ai-browser-contract.md) `popout-posture` for the per-window rule. **External link routing.** The `new-window` event listener calls `openExternalUrl(url)` from [src/renderer/src/lib/platform.ts](/src/renderer/src/lib/platform.ts), which routes through the main process's `shell.openExternal()` after URL validation (http/https only). Inside-the-docs-site links navigate within the webview as normal. **No content cached locally.** The panel always fetches from `docs.omniscio.com` — pages are NOT bundled into Omniscio's installer. This means the docs can ship incrementally (deploy `docs/help-site/` with `npm run docs:deploy`, which syncs the library/roadmap/features/legal mirrors first and THEN runs the firebase deploy — never the raw firebase command on its own) without an Omniscio release. The trade-off is that the panel needs internet to load; offline users see Chromium's standard "no internet" page inside the webview. ## Related - [keyboard-shortcuts.md](keyboard-shortcuts.md) — shortcut catalog including `openHelp` (`Ctrl+Shift+/`) - [INDEX.md](INDEX.md) — this LLM library is a separate doc surface from the help site; the LLM library targets agents, the help site targets humans