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

# Platform Customization

> Customize branding, appearance, and navigation for your organization

Governe lets you customize the platform appearance and navigation to match your organization's brand identity.

## Appearance

Configure visual branding from **Appearance** in the sidebar.

### Platform Identity

| Setting           | Description                              |
| ----------------- | ---------------------------------------- |
| **Platform Name** | Custom name displayed in the header      |
| **Description**   | Tagline or description for your platform |

### Logo

Upload logos for light and dark modes:

| Logo Type      | Recommended Size | Format        |
| -------------- | ---------------- | ------------- |
| **Light Mode** | 200x50 px        | PNG, SVG      |
| **Dark Mode**  | 200x50 px        | PNG, SVG      |
| **Favicon**    | 32x32 px         | PNG, ICO, SVG |

### Colors

Customize the color scheme:

| Color         | Usage                            |
| ------------- | -------------------------------- |
| **Primary**   | Main brand color, buttons, links |
| **Secondary** | Secondary actions, accents       |
| **Accent**    | Highlights, notifications        |

Configure separate colors for dark mode to ensure readability.

### Typography

Set custom fonts:

| Font Type   | Usage                        |
| ----------- | ---------------------------- |
| **Heading** | Page titles, section headers |
| **Body**    | Paragraph text, UI elements  |

Fonts are loaded from Google Fonts or custom URLs.

### Custom CSS

For advanced customization, inject custom CSS:

**CSS URL**: Link to an external stylesheet
**Inline CSS**: Add CSS directly

<Warning>
  Custom CSS can break the UI if not carefully tested. Use browser dev tools to identify correct selectors.
</Warning>

## Legal Pages & App Modals

Governe lets you configure legal content (Terms of Use, Privacy Policy) and per-app warning modals, all managed from the **Appearance → Legal & Warnings** tab.

### Terms of Use (CGU)

Configure a Terms of Use page accessible at `/cgu`:

1. Go to **Governe → Appearance → Legal & Warnings**
2. Edit the **Terms of Use** content using the rich-text editor
3. Click **Save**

Once saved, a link appears automatically in the sidebar. The content version is incremented on each update.

### Privacy Policy Page

Configure a Privacy Policy page accessible at `/privacy-policy`:

1. Go to **Governe → Appearance → Legal & Warnings**
2. Edit the **Privacy Policy** content using the rich-text editor
3. Click **Save**

A link appears in the sidebar alongside the Terms of Use when configured.

<Tip>
  Both legal pages are only visible to users when content has been configured. If no content is set, the links are hidden from the sidebar.
</Tip>

### App Warning Modals

Display a warning modal when users open a specific app (e.g., Chat). The modal requires acknowledgement before the user can proceed.

1. Go to **Governe → Appearance → Legal & Warnings**
2. In the **App Modals** section, select the target app (e.g., `secure-chat`)
3. Edit the warning content using the rich-text editor
4. Click **Save**

**Behavior:**

| Trigger            | Description                                                                      |
| ------------------ | -------------------------------------------------------------------------------- |
| **New session**    | Modal is shown again on each new login                                           |
| **Content update** | Modal is re-shown to all users when the admin updates the content (version bump) |
| **Acknowledged**   | User clicks "I understand" — acknowledgement stored locally until next trigger   |

Modals are app-specific: each app slug (e.g., `secure-chat`, `agent-factory`) can have its own independent warning content and version.

<Accordion title="Technical details">
  * **Storage:** Content is stored as HTML files in the `ai-governance-v2` workspace via the `v1/legal/:type` endpoint
  * **Branding metadata:** Version tracking is stored in `org.branding.appModals[appSlug].version`
  * **Client acknowledgement:** Stored in `localStorage` as `prisme:modal-seen:{orgSlug}:{appSlug}` with `{ version, sessionId }`
  * **Display logic:** The modal is mounted only when the current route matches `/apps/:appSlug` and a version exists for that app slug
</Accordion>

### Privacy Policy Link

Add an external link to your organization's privacy policy, displayed in the footer.

## Menu Editor

Customize the navigation structure from **Menu Editor** in the sidebar.

### Home Page

The **Home Page** setting controls which page users see when they navigate to the root URL (`/`). By default, users land on Chat.

1. Go to **Governe → Menu Editor**
2. Find the **Home Page** dropdown at the top of the editor
3. Select from:
   * **Default (Chat)** — platform default
   * Any menu item with a link (e.g., "Agent Creator", "Knowledges")
4. Click **Save Changes**

<Accordion title="API configuration">
  Update the organization's `navigation` object:

  ```bash theme={null}
  curl -X PATCH "https://api.prisme.ai/v2/orgs/{orgSlug}" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "navigation": {
        "homePage": "/apps/agent-factory",
        "menu": [...]
      }
    }'
  ```

  | Value                   | Behavior                   |
  | ----------------------- | -------------------------- |
  | `undefined` or `""`     | Default (Chat)             |
  | `"/"`                   | Default (no redirect)      |
  | `"/apps/agent-factory"` | Redirects to Agent Creator |
  | `"/apps/ai-knowledge"`  | Redirects to Knowledges    |
  | Any `/apps/*` route     | Redirects to that app      |
  | Any `/builder/*` route  | Redirects to Builder       |

  The `homePage` value must:

  * Start with `/`
  * Contain only alphanumeric characters, hyphens, underscores, and forward slashes
  * Match the pattern: `^\/[a-zA-Z0-9\-_\/]*$`

  Invalid values (e.g., external URLs, paths with query params) are silently ignored for security.
</Accordion>

<Accordion title="Technical details">
  * **Redirect type:** `replace` (doesn't pollute browser history)
  * **Timing:** Redirect happens client-side after authentication
  * **Scope:** Per-organization setting (each org can have a different home page)
  * **Storage:** Stored in `organization.navigation.homePage`
</Accordion>

### Navigation Structure

The menu consists of:

| Section           | Location                 |
| ----------------- | ------------------------ |
| **Main Menu**     | Sidebar navigation       |
| **Footer**        | Bottom of sidebar        |
| **Quick Actions** | Action buttons in header |

### Menu Item Types

| Type         | Description                  |
| ------------ | ---------------------------- |
| **Category** | Group of items with a header |
| **Item**     | Clickable navigation link    |
| **Divider**  | Visual separator             |

### Item Properties

| Property        | Type      | Description                                                  |
| --------------- | --------- | ------------------------------------------------------------ |
| **Label**       | string    | Display text                                                 |
| **Icon**        | string    | Lucide icon key (e.g. `bot`, `shield`, `folder`)             |
| **Color**       | string    | Hex color for icon/label (e.g. `#ef4444`)                    |
| **URL**         | string    | Link destination                                             |
| **Target**      | string    | `_self` (same tab) or `_blank` (new tab)                     |
| **Badge**       | string    | Short label shown as a chip (e.g. "New", "Beta")             |
| **Expanded**    | boolean   | Whether a category starts expanded                           |
| **Permissions** | string\[] | Required permissions — item hidden if user lacks all of them |

### Permission-Based Visibility

Navigation items are filtered based on the user's role permissions at two levels:

**Server-side:** The IAM Context endpoint filters the navigation before returning it, removing items the user cannot access.

**Client-side:** The platform shell applies the same filtering logic:

* Items **with** `permissions` are shown if the user matches **any** listed permission (OR logic). Wildcard matching applies — `agent-factory:*` matches `agent-factory:agents:read`.
* Items **without** `permissions` (empty or omitted) are only shown to platform **super admins** (least privilege by default). Add a `*` permission filter to explicitly **show the item to every user/role**
* Categories are hidden if they have zero visible children after filtering.
* Features within items are also filtered by their own `permissions` array.

### Tier-Based Visibility

Restrict items to subscription tiers:

```yaml theme={null}
visibility:
  tiers:
    - "pro"
    - "enterprise"
  features:
    - "customBranding"
```

### Agent & Template Links

Add dynamic links to agents or templates:

```yaml theme={null}
features:
  - type: agent
    agentId: "agent_123"
    label: "Support Bot"
    slug: "support-bot"
  - type: template
    templateId: "tmpl_456"
    label: "Report Generator"
    slug: "report-gen"
```

<Note>
  **Template features power Builder's "Create new workspace" tiles.** For the full publishing walkthrough — preparing the source workspace, configuration forms, permissions — see [Workspace Templates](./workspace-templates).
</Note>

### Editing the Menu

1. Go to **Menu Editor**
2. Click items to edit properties
3. Drag items to reorder
4. Click **Add Item** to create new entries
5. Click **Save** to apply changes

### Menu Item Examples

**External Link**

```yaml theme={null}
- type: item
  label: "Help Center"
  icon: "help-circle"
  href: "https://help.acme.com"
  target: "_blank"
```

**Internal Section**

```yaml theme={null}
- type: category
  label: "Analytics"
  icon: "chart-bar"
  items:
    - type: item
      label: "Dashboard"
      href: "/analytics/dashboard"
    - type: item
      label: "Reports"
      href: "/analytics/reports"
```

**Protected Item**

```yaml theme={null}
- type: item
  label: "Admin Settings"
  icon: "settings"
  href: "/admin"
  permissions:
    - "orgs:manage"
```

## Best Practices

<CardGroup cols={2}>
  <Card title="Brand Consistency" icon="palette">
    Match colors and fonts to your brand guidelines
  </Card>

  <Card title="Test Dark Mode" icon="moon">
    Verify logos and colors work in both modes
  </Card>

  <Card title="Simplify Navigation" icon="compass">
    Keep menus focused; hide rarely-used items
  </Card>

  <Card title="Use Permissions" icon="shield">
    Show items only to users who can access them
  </Card>
</CardGroup>

## White-Label Configuration

For complete white-labeling (Enterprise tier):

1. **Replace all logos** with your brand
2. **Set platform name** to your product name
3. **Configure colors** to match brand palette
4. **Add custom CSS** for fine-tuning
5. **Customize menu** to show only relevant features
6. **Add privacy policy** link

### Enterprise Features

| Feature         | Description                  |
| --------------- | ---------------------------- |
| Custom domain   | Use your own domain          |
| Email templates | Branded email notifications  |
| Login page      | Custom login design          |
| Support links   | Custom help and support URLs |

## Troubleshooting

<Tabs>
  <Tab title="Logo Not Displaying">
    * Check image URL is publicly accessible
    * Verify image format (PNG, SVG recommended)
    * Check for CORS errors in browser console
    * Try clearing browser cache
  </Tab>

  <Tab title="Colors Not Applying">
    * Ensure hex format (#RRGGBB)
    * Check both light and dark mode colors
    * Custom CSS may override theme colors
    * Clear browser cache after changes
  </Tab>

  <Tab title="Menu Changes Not Visible">
    * Click Save after editing
    * Refresh the page
    * Check permission requirements
    * Verify subscription tier for visibility rules
  </Tab>
</Tabs>

## Next Steps

<CardGroup cols={2}>
  <Card title="Identity & Access" icon="users-gear" href="./identity-access">
    Configure SSO for branded login
  </Card>

  <Card title="Model Governance" icon="robot" href="./model-governance">
    Control AI features available to users
  </Card>
</CardGroup>