Shell

The shell is a platform capability, not part of the kernel. The kernel ships exactly two baked-in surfaces — a sign-in screen and an empty-workspace landing — and nothing else that a user would recognize as chrome. Every header, navigation strip, menu, and edge-anchored surface a user interacts with is delivered by an installable package that has claimed the shell capability. Removing that package does not remove a feature from the kernel; it leaves the platform without a frame.

This page is a contract, not a description of one implementation. The shipped default, “CAOS Core,” lays itself out as a global header over a main canvas, but that shape is a choice, not a requirement. A conforming shell may render a left rail, a split template, or any other arrangement. What it may not do is omit any surface, injection point, or seam named here. The contract exists so that the kernel and every other package can address the shell — mount into it, resolve locations within it, hang guidance off it — without knowing who built it or how it looks.

Throughout this document, “the shell” means whichever package currently holds the shell capability, and “a contributor” means any other package that mounts into the shell’s injection points without owning the capability.

Claiming the shell capability

A package claims the shell by declaring the shell capability in its manifest and registering with the kernel’s Capability Registry at install time. The registry treats shell like any other capability: it enforces one master. At most one installed package may hold the shell capability at a time. A second package that declares shell does not silently co-exist or layer on top; the registry either rejects the claim or performs a governed handoff, never a merge.

Before a claim is accepted, the registry validates the claimant against the capability contract — the set of required surfaces, injection points, and seams enumerated below. A package that declares shell but fails to register a required surface, or fails to expose a required injection point, does not become the master. Conformance is checked at claim time, not discovered at render time.

Whether an installed shell may be replaced by a different package is governed by exposed policy, not kernel rule. The kernel provides the mechanism — it can transfer the shell capability from an incumbent master to a challenger — but it does not decide whether that transfer is permitted. That decision is a setting the incumbent shell surfaces as its own policy. The reigning shell package declares whether it will yield the capability, and under what conditions; the kernel reads and enforces that declaration. This is the platform’s general stance — policy is exposed, not hard-coded — applied to the shell: the kernel never contains a hard rule about shell succession, because the incumbent owns that rule.

The default is deny. Absent an explicit policy from the incumbent permitting replacement, a challenger’s claim is refused and the incumbent remains master. Replacement is an opt-in the sitting shell grants, not a right a challenger asserts.

Required surfaces

Every conforming shell must provide the following surfaces. Each is a named commitment: other packages, and the kernel, rely on these existing regardless of the shell’s visual layout. A shell that renders a left rail instead of a top header still owns every surface below — it merely places them differently.

• Impersonation banner. A persistent, unmissable indication that the current session is acting as another user. When impersonation is active, this surface is visible; when it is not, the surface is absent. Its presence is a safety guarantee: no privileged action may be taken under an assumed identity without the operator being shown that they are impersonating.
• Global header. The shell’s primary chrome region, hosting a fixed set of controls the platform guarantees are always reachable. A conforming header contains, at minimum:
  • an environment chip identifying the current environment (production, sandbox, preview, and so on);
  • global search, the platform-wide entry point for finding records and navigating;
  • help, the entry point to documentation and assistance;
  • a notification bell, the surface for system and app-raised notifications;
  • an avatar menu, the per-user account and session menu;
  • a company-name slot, a brand-bearing region (see the brand seam below);
  • a light/dark theme switch, the control that flips the design-system theme token (see the theme seam below).
• App-navigation strip (primary nav). The strip presenting the current app’s top-level tabs. It is scoped to the active app: switching apps replaces its contents. This is the surface that answers “what are the main areas of the app I am in.”
• Record-tabs strip. The strip presenting the open records or record-level sub-navigation within the current context, distinct from the app’s top-level tabs. It answers “what am I working on inside this area.”
• App switcher (App Launcher). The “waffle” — the surface from which a user moves between installed apps. It is the global pivot across apps, as distinct from the app-navigation strip, which pivots within one app.

The purpose of enumerating these is not to dictate their appearance but to guarantee their existence. Any package, and the kernel itself, may assume that a conforming shell presents each of these surfaces and will honor a contribution aimed at it.

Required injection points

A shell owns its frame, but it does not own everything mounted into it. The contract requires the shell to expose injection points — named seams where other packages contribute content without claiming the shell capability. Each injection point is itself a contract: the shell guarantees that a contributor targeting it will be mounted, positioned, and rendered according to a stable interface, and the contributor guarantees it will supply content that conforms to that interface. This is how a package extends the frame without owning it.

Required injection points:

• Avatar-menu items. A contributor may add entries to the avatar menu (for example, a package-specific settings or sign-out-of-X action). The shell guarantees placement within the menu and a consistent item contract.

• Header actions. A contributor may add controls to the global header alongside the built-in ones. The shell guarantees a defined region and ordering contract for contributed header actions.

• Navigation entries. A contributor may add entries to the app-navigation strip or app switcher for the apps it delivers. The shell guarantees these are rendered as first-class navigation, indistinguishable in behavior from the shell’s own.

• Edge-anchored surfaces. A contributor may mount a surface pinned to a viewport edge. Edge-anchored means the surface is attached to the shell frame, not the current route — it is always reachable regardless of which app or record is open, because it does not unmount when the content region changes. The contract names two canonical examples the platform depends on:

  • the AI assistant orb, anchored bottom-right, and its pinnable right-edge panel — a surface that expands from the orb and may be pinned open along the right edge while the user continues to work;
  • Report-a-Bug, an always-available reporting affordance.

  A conforming shell guarantees that an edge-anchored contribution stays mounted across route changes and remains within reach at all times.

The value of these seams is that contributors never fork or replace the shell to add a menu item, a header button, a nav entry, or a persistent helper. They contribute; the shell composes.

The theme-switch and brand seams

This section states the single most important separation in the contract. The shell provides the control; the kernel provides the mechanism the control flips.

The theme switch in the global header is a control. When toggled, it flips a theme token that the kernel’s design system owns and distributes. The shell does not itself repaint anything. Every surface — the shell’s own chrome, and every component the interpreter renders inside the content region — obtains its colors by reading the theme token, not by carrying its own hard-coded light and dark values. Flipping the token at the design-system level causes every conforming surface to re-render in the new theme, because every surface reads the token rather than embedding a palette.

The brand seam works identically. The company-name slot, and any brand-bearing region, must render from brand seam tokens — a brand mark and wordmark supplied by the design system — rather than from a hard-coded logo or product name baked into the shell package. Rebranding is then a token change, not a shell rebuild, and a white-labeled deployment swaps brand tokens without touching the shell.

The anti-pattern this seam exists to prevent is concrete and was observed in the previous platform generation: a screen hard-coded its own colors instead of reading the theme tokens, so when the theme changed, that screen did not. A surface that bakes in its palette or its brand mark is invisibly non-conforming — it renders correctly until the token it should have read changes, and then it is wrong. The contract’s rule is unconditional: surfaces read the seam; they do not bake it in. A shell, and every component rendered within it, is conformant on this axis only if flipping the theme token and swapping the brand tokens are fully sufficient to change its appearance.

Vocabulary

The shell owns a small set of named regions, and the contract fixes their names so that page templates, guidance, and the interpreter can all refer to the same locations unambiguously:

• global-header — the top-level chrome region and its controls.
• primary-nav — the app-navigation strip (an app’s top-level tabs).
• record-tabs — the record-level tab strip within the current context.
• content — the region into which the interpreter renders the current route’s app, page, and component metadata.

These are named regions, not pixel coordinates. Page templates declare which regions they expose; guidance and the interpreter resolve a location by naming a region, never by measuring the screen. Because the names are fixed by this contract, a differently-laid-out shell — a left rail rather than a top header — still exposes primary-nav and content under the same names, and everything that targets those names continues to work. See the object model for how templates declare regions.

This is also the guidance anchor set

The list of required surfaces above and the set of UI anchors the Guidance Center needs are the same list. This is not a coincidence to be maintained by hand; it is a single set viewed two ways.

Guidance — walkthroughs, tooltips, coach marks, feature callouts — attaches to anchors: stable, named points in the UI described by role, label, icon, and region. Every required shell surface is exactly such a point. When a conforming shell registers its surfaces as anchors — declaring each surface’s role, label, icon, and the named region it occupies — the Guidance Center gets working guidance over the whole frame for free. The environment chip, the notification bell, the app switcher, the theme switch: each becomes addressable by guidance the moment the shell registers it as an anchor.

The converse is the useful diagnostic: a missing anchor degrades guidance exactly where the UI degrades. If a shell omits a surface, guidance that pointed at that surface has nothing to attach to — and the two failures are co-located, so the gap is visible in one place rather than two. A shell that satisfies the required-surfaces contract and registers those surfaces as anchors is, by construction, fully guidable. There is no separate anchor list to keep in sync.

What the kernel guarantees because the shell is filled

With a shell registered as master, the kernel’s interpreter renders in a fixed order:

1. It renders the shell’s frame — the global header, the navigation strips, the impersonation banner when active, and every registered surface and edge-anchored contribution.
2. It applies the design system, distributing the theme and brand tokens the shell’s controls flip and the shell’s brand slot reads.
3. It interprets the current route’s metadata — the app, page, and component definitions for wherever the user has navigated — and renders that interpretation inside the shell’s content region, never outside the frame.
4. Every read performed along the way — every record, field, and metadata lookup — passes through the access engine, so the frame and its contents show only what the current identity is permitted to see.

The consequence is the point of the whole contract: swap the shell package and the entire frame changes with no kernel change. Because the kernel renders a shell rather than the shell — addressing it only through the capability, the named regions, and the injection points defined here — a different conforming package produces a different-looking platform while the interpreter, the design system, the access engine, and every other package continue unchanged. The shell is replaceable precisely because it is a contract and not code the kernel depends on.

See the Overview for how the shell capability sits among the platform’s other capabilities, and the kernel for the interpreter and Capability Registry that enforce this contract.