Date: 2026-03-25 Status: Design / Active Scope: The Shell-level overview surface that summarizes graph truth, Workbench truth, and shell/runtime truth without collapsing them into one abstraction.

Related:

• SHELL.md — Shell host and orchestration boundary
• ../../technical_architecture/unified_view_model.md — five-domain model and shell overview role
• ../../technical_architecture/graphlet_model.md — graphlet semantics used by the overview
• ../navigator/NAVIGATOR.md — Navigator projection domain
• ../workbench/WORKBENCH.md — Workbench arrangement authority
• ../graph/GRAPH.md — Graph domain spec; the canvas is its primary rendered surface

Graphshell needs a surface that answers:

• what graph context am I in,
• what is open and foregrounded,
• what is the application doing right now,
• what needs my attention,
• where should I go next?

This is a Shell concern because it spans multiple domains at once.

The overview must summarize them without pretending they are one thing.

The Shell overview must present three parallel truths.

The overview must show correspondences among those truths, not flatten them.

The default Shell overview should be built from six modules.

Always-visible summary of:

• active graph/view target,
• active graphlet name or kind,
• current scope token,
• current focus authority.

Summarizes:

• primary and secondary targets,
• active graphlet members/count,
• current graphlet kind,
• nearby frontier candidates,
• component or path summary when relevant.

Summarizes:

• active frame,
• active tile group / tab group,
• focused pane,
• open pane count,
• linked or detached graphlet binding state when relevant.

Summarizes:

• current viewer backend,
• fallback/degraded state,
• content kind,
• per-content attention flags such as blocked permissions or unsupported type.

Summarizes:

• diagnostics warnings,
• background jobs,
• sync/presence state,
• trust/security state,
• current focus-return anchor if a modal or overlay is active.

Provides action-oriented suggestions such as:

• open frontier,
• show path,
• reveal in graph,
• reopen linked graphlet,
• resolve fallback viewer,
• inspect diagnostics.

One plausible desktop layout:

┌──────────────────────────────────────────────────────────────────────┐
│ Active Context: Graph A · Component graphlet · Frame 2 · Pane 5     │
├──────────────────────────────┬───────────────────────────────────────┤
│ Graph Context                │ Workbench Context                     │
│ - active graphlet            │ - frame / group / pane               │
│ - primary/secondary targets  │ - linked vs detached                 │
│ - frontier / path summary    │ - open pane count                    │
├──────────────────────────────┼───────────────────────────────────────┤
│ Viewer / Content             │ Runtime / Attention                  │
│ - backend + content kind     │ - diagnostics / sync / trust         │
│ - fallback state             │ - background jobs                    │
├──────────────────────────────────────────────────────────────────────┤
│ Suggested Next Actions                                            │
└──────────────────────────────────────────────────────────────────────┘

This may be rendered as:

• a transient overlay in graph-first mode,
• a pinned Workbench tool pane,
• a compact mode in a Shell host region.

Shell owns:

• overview surface composition,
• module ordering,
• command routing from the overview,
• attention prioritization,
• app-level visibility policy.

Graph supplies:

• active targets,
• graphlet facts,
• path/component/loop/facet summaries,
• graph-side diagnostics relevant to current context,
• graph-view slot layout truth for the overview plane: create, rename, move, archive, and restore.

Navigator supplies:

• active graphlet identity,
• breadcrumb/context strings,
• scoped search context,
• frontier candidates,
• graphlet transition suggestions.

Workbench supplies:

• active frame/group/pane summary,
• linked vs detached arrangement state,
• foregrounding and staging status,
• open-pane correspondence information.

Viewer supplies:

• viewer backend,
• content kind,
• fallback/degraded reason,
• content-local state worth surfacing to the host.

The overview should make the role of each domain legible.

This is the shortest honest explanation of how the domains work together in UI.

The overview is not just passive status.

Minimum interactions:

• clicking a graph target summary reveals it in graph,
• clicking a graphlet summary opens or focuses the matching Navigator graphlet view,
• clicking a frame/pane summary foregrounds it in Workbench,
• clicking a viewer backend or fallback state opens viewer diagnostics or Render With,
• clicking a runtime warning routes to the owning diagnostics or control surface,
• graph-view slot create/rename/move/archive/restore actions dispatch Graph intents because the graph layout manager owns that slot truth,
• focus/open/transfer/close overview-surface actions dispatch Workbench intents because they change surface routing rather than graph truth,
• action suggestions dispatch to the owning domain rather than mutating state directly in Shell.

The overview should support at least three modes.

One-line or one-row summary for persistent shell chrome.

Two-column or card-based summary for regular use.

Expanded mode with more subsystem/runtime visibility and fewer productivity shortcuts.

The overview should treat the active graphlet as the primary unit of current graph context.

That means it should show:

• graphlet kind,
• anchor(s),
• member count,
• current layout/presentation mode if relevant,
• linked Workbench binding state if one exists,
• next-best graphlet transitions when helpful.

This is the most concrete way the overview makes Navigator and Graph collaborate in the UI.

1. User is on the canvas.
2. Overview shows Ego graphlet · 14 nodes · 3 frontier candidates.
3. User clicks a frontier candidate.
4. Shell routes to Navigator for graphlet transition.
5. Graph and Navigator update; Workbench remains absent.

1. User has 6 panes open across 2 frames.
2. Overview shows Frame B · detached arrangement · viewer:fallback in 1 pane.
3. User clicks the fallback warning.
4. Shell routes to Workbench + Viewer diagnostics.

1. Focused node enters degraded trust state.
2. Overview shows warning in Runtime / Attention card.
3. User clicks it.
4. Shell routes to the owning diagnostics or trust surface while preserving graph/workbench context.

The overview surface is coherent when:

1. it clearly separates graph, Workbench, and shell/runtime truth,
2. it names the active graphlet and current work context,
3. it exposes domain-specific attention without lying about ownership,
4. its commands always route to the owning domain,
5. it works both with and without the Workbench being active,
6. it makes the five domains more legible to the user rather than less.