> ## Documentation Index
> Fetch the complete documentation index at: https://getoverlay.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Customizing Overlay

> Brand, theme, navigation, extensions, and feature visibility for enterprise deployments.

The web app is the canonical surface for enterprise customization. Self-hosters should start in `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.

```ts theme={null}
import {
  DEFAULT_OVERLAY_NAVIGATION,
  defineOverlayAppConfig,
} from '@overlay/app-core/app-shell'

export const overlayAppShell = defineOverlayAppConfig({
  brand: {
    name: 'Acme AI',
    shortName: 'Acme',
    logoSrc: '/assets/acme-logo.png',
    homeHref: '/app/chat',
    supportEmail: 'it@acme.example',
  },
  navigation: [
    ...DEFAULT_OVERLAY_NAVIGATION,
    {
      id: 'admin',
      label: 'Admin',
      href: '/app/admin',
      icon: 'shield-check',
      componentKey: 'acme.nav.admin',
    },
  ],
  featureFlags: [
    { id: 'knowledge', label: 'Knowledge', enabled: true },
    { id: 'extensions', label: 'Extensions', enabled: false },
  ],
})
```

Registries merge with defaults by `id`. If you provide an item with the same `id`, Overlay replaces that item’s metadata. Unspecified default items remain available.

## Component Keys

Bootstrap returns serializable metadata only. React renderers are local to each surface and are referenced by stable `componentKey` 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:

```ts theme={null}
import { defineOverlayExtension } from '@overlay/extension-sdk'

export const studentRevisionExtension = defineOverlayExtension({
  id: 'student-revision',
  version: '1.0.0',
  navigation: [{ id: 'student-revision', label: 'Student Revision', href: '/app/x/student-revision', icon: 'sparkles' }],
  featureModules: [{
    id: 'student-revision',
    label: 'Student Revision',
    routePatterns: ['/app/x/student-revision'],
    componentKey: 'student.modules.revisionDashboard',
  }],
  apiHandlers: [{
    method: 'GET',
    path: '/overview',
    handler: async () => Response.json({ ok: true }),
  }],
})
```

Register app metadata through `extendOverlayAppConfig`, map React renderers in `src/extensions/registry.tsx`, and keep authenticated API handlers under `/api/v1/extensions/:extensionId/:path`.

## Feature Visibility

Use `featureFlags` 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.

## Model Providers

Register model provider metadata in `modelProviders`. 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.