src/overlay.config.ts, then use the shared package APIs from @overlay/app-core, @overlay/extension-sdk, @overlay/api-client, @overlay/ui, @overlay/chat-core, @overlay/chat-react, and @overlay/modules-react.
Brand, Theme, And Navigation
src/overlay.config.ts is a serializable app registry. It can replace brand metadata, add navigation destinations, hide feature-gated surfaces, register settings panels, and describe custom tools or integrations.
The default brand mark is the OverlayMark SVG orb component (@overlay/ui, re-exported from
src/components/orb/Orb.tsx), not the logoSrc raster: the sidebar renders the orb whenever
brand.logoSrc is the default /assets/overlay-logo.png, and only renders the next/image raster
when a custom brand overrides it. The same Orb component also renders the small marks inside the
chat surface — tool-call rails, the reasoning (“Thinking”/“Thought”) row, the streaming tail marker,
the exchange loading state, and the notebook agent panel — so no surface falls back to the PNG.
The PNG asset stays on disk for lifecycle emails and favicons, which require raster. Agent avatars
are anthropomorphic creatures (AgentCreature in src/components/orb/Creature.tsx): a solid-color
body in one of eight shapes (avatarShape: circle, blob, squircle, pill, triangle, hexagon, cloud,
droplet) with Grokbot-style blinking eyes whose dark/light tone derives from the body luminance.
Both shape and color (avatarColor) persist on the workspace agent record — nullable columns with a
circle default, so existing agents keep working — and are picked in the agent editor’s Identity
section, which previews shapes and colors as live creatures.
id. If you provide an item with the same id, Overlay replaces that item’s metadata. Unspecified default items remain available.
Agents lead the default primary navigation and /app/agents is the authenticated home. The authenticated Agents surface uses the contextual sidebar as its roster; selecting an agent opens that agent’s direct conversation. The conversation header’s settings control composes the existing agent editor inside AppScreenSidePanel, which is docked on desktop and presented as an overlay dialog on smaller screens. The full-page /app/agents/new and /app/agents/:id routes remain compatibility entry points.
While Settings is open, the primary rail exposes a temporary return item after the normal navigation list. It uses the existing X icon and the label Settings, and returns the user to Agents; it should not be inserted at the top of the primary navigation.
Component Keys
Bootstrap returns serializable metadata only. React renderers are local to each surface and are referenced by stablecomponentKey strings. For example, a settings panel can declare componentKey: 'acme.settings.security'; the web app maps that key to a local React component, while mobile can map the same key to a React Native renderer or ignore it.
Build-Time Extensions
Use@overlay/extension-sdk for trusted extensions that are bundled at build time:
extendOverlayAppConfig, map React renderers in src/extensions/registry.tsx, and keep authenticated API handlers under /api/v1/extensions/:extensionId/:path.
Feature Visibility
UsefeatureFlags for coarse product areas and policyGates for enterprise policy. Feature flags remove gated registry entries from bootstrap when disabled. Policy gates let surfaces show disabled states, warnings, or hidden entries without changing backend route behavior.
Capability gates are evaluated per registry entry. Memory management in Settings requires the memory capability only; vectorSearch controls semantic retrieval and search tooling independently, so disabling vector search must not hide saved-memory management.
The default agent-environments settings section is gated by the agents feature flag and the
server-derived connectedAgents capability. It is labeled Environments, uses a distinct server
icon in settings navigation, and follows the standard elevated settings-card surface with compact
subtle icon tiles. New local, VPS, customer-sandbox, and Overlay Cloud environments are created
inside the Bring Your Own Agent branch of the agent editor. The Settings renderer is the fleet
administration surface: it shows health and pending verification, collects or changes explicit
project roots, and exposes revocation. For the production workspace rollout,
the agent editor offers existing environments or one outbound connection command
for a user-owned computer, VPS, or sandbox. Overlay Cloud is deliberately absent
until the managed-environment release gates in docs/develop/bring-your-own-agents.md pass. The
backend additionally requires
features.connectedAgentControlPlane; the capability mirrors that server policy and cannot be
enabled by a client assertion.
Workspace Memories
Memories are shared workspace resources with member attribution. Settings > Memories defaults toAll and uses one dropdown containing All plus every active human member; selecting a member reloads only memories attributed to that member. Creator names are shown on memory cards. Members may copy any visible workspace memory, while selection and delete controls appear only on memories they created.
Personal workspace settings expose the same collaboration controls as other
workspaces. The archive action and ownership-transfer option remain unavailable
because the Personal workspace and its creating owner are permanent account
lifecycle anchors.
Account Settings
All ordinary full-page product destinations use the shared app shell. This includes account settings, sign-in, sign-up, password recovery, mobile authentication completion, desktop downloads, and legal pages./account is a compatibility URL
that redirects to /app/settings?section=account so the client receives the
canonical settings section instead of falling back to General.
Protocol-only auth callbacks, auto-closing integration popups, public token share
pages, and visual fixtures remain standalone. Their minimal surfaces are part of
the handoff, popup, recipient, or test contract and must not gain workspace
navigation.
The account panel contains identity, desktop handoff, and deployment-supported billing controls. Do not expose account-level API-key controls unless the deployment intentionally enables and tests the API-key service; a non-working credential control is worse than no control.
workspaceWallets is disabled by default. It requires OVERLAY_FEATURE_WORKSPACE_WALLETS=1 plus OVERLAY_WORKSPACE_BILLING_ROLLOUT_STAGE=internal|selected|general. internal enables only OVERLAY_WORKSPACE_BILLING_INTERNAL_WORKSPACE_IDS; selected adds OVERLAY_WORKSPACE_BILLING_SELECTED_WORKSPACE_IDS; general enables every organization workspace. Non-selected workspaces preserve personal compatibility. A selected organization workspace requires its own active, funded account and never falls back to a member’s personal wallet. Next.js and hosted Convex use the same rollout parser so background indexing cannot diverge from interactive work.
The workspace Billing tab is visible throughout rollout. It shows rollout status before eligibility, wallet setup for selected owners/admins, separate allowance and top-up balances, recurring checkout, one-time direct workspace top-ups, the Stripe portal, and an owner/admin margin and reconciliation report. Members are read-only. Personal-wallet transfers and member contributions are intentionally absent.
Model Providers
Register model provider metadata inmodelProviders. Use modelPolicy hooks for local model filtering and defaults. Hooks are not serialized to bootstrap; only serializable model provider metadata is returned to other surfaces.