# Theme Overview

## Overview

Themes allow you to customize the visual appearance and user interface of your PteroCA panel. Introduced in **v0.4**, the theme system provides a flexible way to change colors, layouts, and the overall look of your installation without modifying core code.

### What Themes Can Change

Themes control the appearance of:

* **Admin Panel Interface**: Colors, layouts, and styling of the administrative interface
* **Client Area**: Dashboard, server management, shop appearance
* **Authentication Pages**: Login, registration, password reset pages
* **Email Templates**: Branded email notifications
* **Error Pages**: Custom 404, 500, and other error pages
* **Forms and Components**: Input fields, buttons, and UI elements

### Benefits of Using Themes

* **Consistent Branding**: Match your panel to your company's visual identity
* **User Experience**: Provide a unique and polished interface for your customers
* **Dark Mode Support**: Many themes offer automatic light/dark mode switching
* **Easy Updates**: Themes are isolated from core code, making PteroCA updates safer
* **No Code Required**: Install and configure themes through the Admin Panel

{% hint style="info" %}
**Theme System Available in v0.4+**

The theme system was introduced in PteroCA v0.4. If you're running an earlier version, please upgrade to access theme functionality.
{% endhint %}

***

## Theme Contexts

**New in v0.6.3:** PteroCA supports multiple theme contexts, allowing you to use different themes for different parts of your panel.

### Available Contexts

PteroCA supports three distinct contexts:

| Context     | Description                 | Setting         | Use Case                                           |
| ----------- | --------------------------- | --------------- | -------------------------------------------------- |
| **panel**   | Admin panel and client area | `PANEL_THEME`   | Main panel interface, dashboard, server management |
| **landing** | Public landing page         | `LANDING_THEME` | Marketing site, homepage, public-facing pages      |
| **email**   | Email templates             | `EMAIL_THEME`   | Transactional emails, notifications                |

### How Context Works

Each theme declares which contexts it supports in its `template.json` file:

```json
{
  "template": {
    "name": "my-theme",
    "contexts": ["panel", "email"]
  }
}
```

This theme can be activated for panel and email contexts, but not for landing pages.

### Configuring Context-Specific Themes

You can set different themes for each context:

1. Navigate to **Settings → Theme**
2. Configure each context independently:
   * **Panel Theme** (`PANEL_THEME`) - Used for admin and client interfaces
   * **Landing Theme** (`LANDING_THEME`) - Used for public landing pages
   * **Email Theme** (`EMAIL_THEME`) - Used for email templates
3. Only themes supporting the specific context appear in each dropdown

**Example configuration:**

* Panel: "dark-professional" theme
* Landing: "marketing-bright" theme
* Email: "simple-email" theme

{% hint style="info" %}
**Single Theme for All Contexts**

If a theme supports all three contexts, you can use the same theme everywhere for consistent branding. Simply select it for all three settings.
{% endhint %}

***

## Default Theme

PteroCA comes with a built-in **default** theme that provides a modern, professional interface.

### Default Theme Features

* **Name**: Default Theme
* **Version**: 1.1.1
* **Author**: PteroCA.com
* **License**: MIT

**Capabilities:**

* ✅ Full dark mode support (automatic light/dark switching)
* ✅ Custom color configuration (primary colors for light and dark modes)
* ✅ Bootstrap 5 based design
* ✅ Responsive layout (mobile-friendly)
* ✅ EasyAdmin integration (admin panel interface)
* ✅ Custom error pages (404, 500)
* ✅ Email template styling

**Default Colors:**

* Light mode primary: `#4e73df` (Blue)
* Dark mode background: `#2e59d9` (Darker Blue)

The default theme is always available as a fallback if another theme fails to load.

***

## Finding Themes

### PteroCA Marketplace

{% hint style="success" %}
**PteroCA Marketplace** - Official Theme Repository

The [PteroCA Marketplace](https://marketplace.pteroca.com) is the primary source for verified, curated themes. Browse professional themes, read reviews, and download securely.

**Features:**

* ✅ Security-reviewed themes
* ✅ Community reviews and ratings
* ✅ Verified developers
* ✅ Version compatibility checking
* ✅ Official and community themes
* ✅ Free and premium themes

**Visit:** [marketplace.pteroca.com](https://marketplace.pteroca.com)
{% endhint %}

**Benefits of using the marketplace:**

* **Quality Assurance**: Themes are reviewed for quality and compatibility
* **Security**: Themes undergo security checks before listing
* **Support**: Direct contact with theme developers
* **Updates**: Easy access to theme updates and new versions
* **Reviews**: Read real user experiences before downloading

### Other Theme Sources

**Community Resources:**

* [PteroCA Discord Server](https://discord.com/invite/Gz5phhuZym) - Community theme sharing
* [GitHub](https://github.com/topics/pteroca-theme) - Open-source themes

**Third-Party Sources:**

* Developer portfolios and personal websites
* Custom theme commissions from developers

{% hint style="warning" %}
**Download Themes from Trusted Sources**

Only install themes from developers you trust. Themes have access to your panel's templates and can potentially include malicious code. Always review theme files before installation.

**Recommended:** Use the [PteroCA Marketplace](https://marketplace.pteroca.com) for verified, security-reviewed themes.
{% endhint %}

### Custom Themes

You can also commission custom themes from developers or create your own. See the [Creating Your Own Themes](#creating-your-own-themes) section for more information.

***

## Installing Themes

Installing a theme involves placing the theme files in the correct directory and ensuring proper structure.

### Prerequisites

Before installing a theme:

* Access to your server's file system (SSH, SFTP, or file manager)
* Theme files (usually provided as a ZIP archive or folder)
* Write permissions on the `/themes/` directory

### Installation Steps

#### Step 1: Obtain Theme Files

1. Download the theme from a trusted source
2. Extract the archive if it's in ZIP format
3. Verify the theme folder contains a `template.json` file

**Valid theme structure:**

```
my-theme/
├── template.json          # Required: Theme metadata
├── base.html.twig        # Base template
├── assets/
│   ├── css/              # Stylesheets (optional)
│   ├── js/               # JavaScript (optional)
│   └── fonts/            # Custom fonts (optional)
├── panel/                # Admin panel templates (optional)
├── bundles/              # Bundle overrides (optional)
├── components/           # Reusable components (optional)
└── email/                # Email templates (optional)
```

#### Step 2: Upload Theme to Server

1. Connect to your server via SSH, SFTP, or file manager
2. Navigate to the PteroCA installation directory
3. Locate the `/themes/` folder (e.g., `/var/www/pteroca/themes/`)
4. Upload/copy the theme folder into `/themes/`

**Example:**

```bash
# Via SSH
cd /var/www/pteroca/themes/
unzip my-theme.zip
# or
cp -r /path/to/my-theme ./
```

**Result:**

```
/var/www/pteroca/themes/
├── default/              # Default theme (always present)
│   └── template.json
└── my-theme/             # Your new theme
    └── template.json
```

#### Step 3: Set Permissions (if needed)

Ensure the web server can read the theme files:

```bash
chown -R www-data:www-data /var/www/pteroca/themes/my-theme
chmod -R 755 /var/www/pteroca/themes/my-theme
```

Replace `www-data` with your web server user if different (e.g., `nginx`, `apache`).

#### Step 4: Place Theme Assets (if applicable)

If the theme includes CSS, JavaScript, or image assets, place them in the public assets directory:

1. Navigate to `/public/assets/theme/`
2. Create a folder matching your theme name (e.g., `my-theme`)
3. Upload compiled assets (CSS, JS, images, fonts)

**Example:**

```
/public/assets/theme/
├── default/
│   ├── css/
│   ├── js/
│   └── fonts/
└── my-theme/
    ├── css/
    │   └── app.css       # Main stylesheet
    ├── js/
    │   └── custom.js     # Custom scripts
    └── img/
        └── logo.png      # Theme logo
```

{% hint style="info" %}
**Asset Directory Naming**

The asset folder name **must match** your theme folder name. If your theme is `/themes/my-theme/`, assets must be in `/public/assets/theme/my-theme/`.
{% endhint %}

#### Step 5: Verify Installation

1. Log in to the Admin Panel
2. Navigate to **Settings → Theme**
3. Your theme should appear in the "Current theme" dropdown
4. If it doesn't appear, check the [Troubleshooting](#troubleshooting) section

***

## Activating Themes

Once installed, you can activate a theme through the Admin Panel.

### Activation Steps

1. Log in to the **Admin Panel** with an account that has theme management permissions
2. Navigate to **Settings** in the left sidebar
3. Click **Theme** in the settings menu
4. Locate the **"Current theme of the panel"** setting
5. Click **Edit** (pencil icon)
6. Select your desired theme from the dropdown list
7. (Optional) Click the **ℹ️ icon** next to a theme to view its information (version, author, features)
8. Click **Save**

**What happens when you activate a theme:**

1. ✅ System validates the theme has a valid `template.json`
2. ✅ Theme templates become active immediately (no restart needed)
3. ✅ Theme assets are loaded on next page load
4. ✅ Color and dark mode settings adjust based on theme capabilities
5. ✅ Users see the new theme on their next page load

{% hint style="success" %}
**Instant Theme Switching**

Theme changes take effect immediately. Simply refresh your browser to see the new theme in action.
{% endhint %}

### Switching Back to Default

If you encounter issues with a custom theme, you can always switch back to the default theme:

1. Go to **Settings → Theme**
2. Select **"default"** from the theme dropdown
3. Click Save

The system automatically falls back to the default theme if an active theme is invalid or missing.

***

## Managing Themes

**New in v0.6.3:** PteroCA includes a comprehensive theme management interface for uploading, copying, exporting, and deleting themes.

### Accessing Theme Management

1. Log in to the **Admin Panel** with theme management permissions
2. Navigate to **Themes** in the left sidebar
3. View all installed themes with their details

### Theme List

The theme list displays:

* **Name**: Theme identifier and display name
* **Version**: Current theme version
* **Author**: Theme creator
* **Contexts**: Supported contexts (panel, landing, email)
* **Status**: Whether theme is currently active in any context
* **Actions**: Available operations (view, set default, copy, export, delete)

### Theme Operations

#### Viewing Theme Details

1. Click on a theme in the list
2. View comprehensive information:
   * Metadata (name, version, author, license)
   * Supported contexts
   * Compatibility (PteroCA version, PHP version)
   * Feature support (dark mode, custom colors)
   * Active status per context

#### Setting Default Theme

1. Click **Set Default** button next to a theme
2. Select the context (panel, landing, or email)
3. Confirm the change
4. Theme becomes active for that context immediately

**Requirements:**

* Theme must support the selected context
* User must have `set_default_theme` permission

#### Uploading Themes

Upload new themes as ZIP packages:

1. Click **Upload Theme** button
2. Select a theme ZIP file
3. System validates:
   * Valid `template.json` file
   * Correct directory structure
   * Unique theme name (no conflicts)
4. Theme is extracted and registered
5. Assets are published to public directory

**ZIP package structure:**

```
my-theme.zip
└── my-theme/
    ├── template.json
    ├── panel/
    ├── landing/
    ├── email/
    └── assets/
```

{% hint style="warning" %}
**Theme Name Conflicts**

If a theme with the same name already exists, upload will fail. Delete or rename the existing theme first, or use the Copy feature to create a variant.
{% endhint %}

#### Copying Themes

Create a copy of an existing theme:

1. Click **Copy** button next to a theme
2. Enter a new name for the copy
3. System creates duplicate with new name
4. Edit the copy without affecting the original

**Use cases:**

* Create theme variants (light/dark versions)
* Backup before making changes
* Build on existing themes

#### Exporting Themes

Export themes as ZIP packages:

1. Click **Export** button next to a theme
2. System packages theme files and assets
3. Download ZIP archive
4. Share with others or backup

**What's included:**

* All template files
* `template.json` metadata
* Assets (CSS, JS, images)
* Proper directory structure for re-upload

#### Deleting Themes

Remove themes from the system:

1. Click **Delete** button next to a theme
2. Confirm deletion
3. Theme files and database records are removed

**Restrictions:**

* Cannot delete the default theme
* Cannot delete currently active themes
* Must deactivate theme from all contexts first

{% hint style="danger" %}
**Deletion is Permanent**

Deleted themes cannot be recovered unless you have a backup. Consider exporting themes before deletion.
{% endhint %}

***

## Theme Configuration

Many themes support customization options, allowing you to adjust colors and appearance without modifying theme files.

### Available Configuration Options

The configuration options available depend on your active theme's capabilities:

#### 1. Current Theme

**Setting:** `Current theme of the panel`

**Description:** Select which theme is active for your panel.

**Available for:** All installations

**How to use:**

* Select from dropdown of installed themes
* Click the info icon to see theme details
* Save to apply immediately

#### 2. Custom Colors (if supported)

**Settings:**

* `Default color for light mode` - Primary UI color in light mode
* `Default background color for dark mode` - Background color in dark mode

**Description:** Customize the color scheme of your theme without editing CSS files.

**Available for:** Themes with `supportCustomColors: true` in template.json

**How to use:**

1. Click the color picker field
2. Choose a color or enter a hex code (e.g., `#FF5733`)
3. Preview updates in real-time
4. Click Save to apply globally

**What these colors affect:**

* **Light mode color**: Buttons, links, active menu items, highlights
* **Dark mode color**: Sidebar background, content area background, dark mode UI elements

{% hint style="info" %}
**Theme Must Support Custom Colors**

If you don't see color configuration options, your active theme doesn't support custom colors. Switch to a different theme or contact the theme developer.
{% endhint %}

#### 3. Dark Mode Settings (if supported)

**Setting:** `Disable dark mode`

**Description:** Completely disable dark mode for all users.

**Available for:** Themes with `supportDarkMode: true` in template.json

**Options:**

* **Unchecked (default)**: Users can toggle between light and dark modes
* **Checked**: Dark mode is disabled; users only see light mode

**Use cases:**

* Your branding requires light mode only
* Dark mode conflicts with custom styling
* Simplify user interface options

**Setting:** `Default theme mode`

**Description:** Set the default color scheme for users who haven't chosen a preference.

**Available for:** Themes with dark mode support and dark mode not disabled

**Options:**

* **Light**: Always use light mode by default
* **Dark**: Always use dark mode by default
* **Auto**: Follow user's system preference (operating system dark mode setting)

**Note:** Users can still override this preference in their account settings unless dark mode is completely disabled.

### Configuration Best Practices

**Choose colors carefully:**

* Test colors in both light and dark modes
* Ensure sufficient contrast for readability
* Consider color blindness accessibility
* Preview on different devices and screen sizes

**Dark mode considerations:**

* If your brand has strict color requirements, consider disabling dark mode
* Auto mode provides the best user experience for most users
* Test custom colors in both modes before finalizing

***

## Theme Features and Capabilities

Themes can declare which features they support in their `template.json` file.

### Feature Flags

Themes use feature flags to indicate capabilities:

| Feature               | Description                                 | Impact on Admin Settings              |
| --------------------- | ------------------------------------------- | ------------------------------------- |
| `supportDarkMode`     | Theme supports light and dark color schemes | Shows dark mode configuration options |
| `supportCustomColors` | Allows admin to configure custom colors     | Shows color picker fields in settings |

### How to Check Theme Features

**Method 1: Admin Panel**

1. Go to **Settings → Theme**
2. Click the **ℹ️ icon** next to a theme name
3. View "Options" section showing supported features

**Method 2: API**

```bash
curl -X GET https://your-panel.com/panel/api/template/theme-name \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

**Response:**

```json
{
  "Template name": "my-theme",
  "Version": "1.0.0",
  "Options": {
    "Support dark mode": true,
    "Allow configuring custom colors": true
  }
}
```

### What Happens When Features Are Disabled

**If `supportDarkMode: false`:**

* Dark mode settings hidden in Admin Panel
* Users cannot toggle dark mode
* Theme always displays in light mode

**If `supportCustomColors: false`:**

* Color picker fields hidden in Admin Panel
* Theme uses its built-in color scheme
* Custom colors cannot be applied

***

## Theme Assets and Resources

Themes use assets like CSS, JavaScript, images, and fonts to create their visual appearance.

### Asset Structure

**Theme source files:** `/themes/{theme-name}/assets/`

* May contain source files (SCSS, uncompiled JS)
* Not directly served to browsers

**Public compiled assets:** `/public/assets/theme/{theme-name}/`

* Compiled and optimized files
* Served directly to users' browsers
* Accessible via web URLs

### Asset Types

**CSS Stylesheets:**

* Main styles: `app.css`
* Page-specific: `panel.css`, `errors.css`
* Loaded automatically by theme

**JavaScript:**

* Custom interactive features
* Libraries (Chart.js, etc.)
* Loaded in theme templates

**Images:**

* Logos, icons, backgrounds
* Referenced in templates or CSS

**Fonts:**

* Custom typography
* Web fonts (WOFF2, TTF)

### How Assets Are Loaded

Themes reference assets using the `template_asset()` Twig function:

```twig
<link rel="stylesheet" href="{{ template_asset('css/app.css') }}">
<script src="{{ template_asset('js/custom.js') }}"></script>
```

**Generated URL:**

```
https://your-panel.com/assets/theme/my-theme/css/app.css
https://your-panel.com/assets/theme/my-theme/js/custom.js
```

### Asset Best Practices

**For theme installation:**

* Always place assets in `/public/assets/theme/{theme-name}/`
* Match folder name exactly to theme name
* Ensure proper file permissions (readable by web server)

**For troubleshooting:**

* Check browser console for 404 errors on assets
* Verify asset files exist in public directory
* Check web server has read access to asset files

***

## Permissions

To manage themes, users need specific permissions:

| Permission          | Action                   | Description                            |
| ------------------- | ------------------------ | -------------------------------------- |
| `access_themes`     | View theme list          | Access the theme management interface  |
| `view_theme`        | View theme details       | See detailed theme information         |
| `set_default_theme` | Set default theme        | Activate themes for different contexts |
| `configure_theme`   | Configure theme settings | Adjust theme colors and options        |
| `upload_theme`      | Upload themes            | Install new theme packages             |
| `copy_theme`        | Copy themes              | Duplicate existing themes              |
| `export_theme`      | Export themes            | Download themes as ZIP packages        |
| `delete_theme`      | Delete themes            | Remove themes from system              |

### Default Permissions

* **Admin role**: Has all theme permissions by default
* **User role**: No theme permissions by default

For detailed information about the permission system, see [Access Control](/access-and-permissions/access-control/roles-and-permissions.md).

***

## Troubleshooting

Common issues and solutions when working with themes.

### Theme Not Appearing in Selection

**Symptoms:** Installed theme doesn't show up in the theme dropdown.

**Possible causes:**

* Missing `template.json` file
* Invalid JSON syntax in `template.json`
* Incorrect folder structure
* Missing required fields in `template.json`

**Solutions:**

1. **Verify template.json exists:**

```bash
ls /var/www/pteroca/themes/my-theme/template.json
```

2. **Validate JSON syntax:**

```bash
cat /var/www/pteroca/themes/my-theme/template.json | jq .
```

If jq reports an error, fix the JSON syntax.

3. **Check required fields:**

```json
{
  "template": {
    "name": "my-theme",
    "version": "1.0.0",
    "pterocaVersion": "0.6",
    "phpVersion": ">=8.2"
  }
}
```

4. **Verify folder name matches template name:** Folder: `/themes/my-theme/` JSON: `"name": "my-theme"` (must be identical)

### Custom Colors Not Applying

**Symptoms:** Color picker settings don't change the panel appearance.

**Cause:** Theme doesn't support custom colors.

**Solutions:**

1. **Check theme capabilities:**
   * Go to Settings → Theme
   * Click info icon next to theme name
   * Check "Allow configuring custom colors" option
2. **If feature is missing:**
   * Switch to a theme with custom color support
   * Contact theme developer to request feature
   * Use the default theme (supports custom colors)
3. **Clear browser cache:**
   * Press Ctrl+Shift+Delete (Cmd+Shift+Delete on Mac)
   * Clear cached images and files
   * Refresh page

### Dark Mode Settings Not Visible

**Symptoms:** Can't find dark mode configuration options.

**Cause:** Theme doesn't support dark mode.

**Solutions:**

1. **Check theme capabilities:**
   * Verify theme has `"supportDarkMode": true` in template.json
2. **Switch themes:**
   * Choose a theme with dark mode support
   * Default theme supports dark mode

### Theme Assets Not Loading (404 Errors)

**Symptoms:** Broken styling, missing images, browser console shows 404 errors.

**Causes:**

* Assets not uploaded to `/public/assets/theme/{theme-name}/`
* Incorrect folder name (doesn't match theme name)
* File permissions issue

**Solutions:**

1. **Verify assets directory exists:**

```bash
ls /var/www/pteroca/public/assets/theme/my-theme/
```

2. **Check folder name matches:**
   * Theme folder: `/themes/my-theme/`
   * Asset folder: `/public/assets/theme/my-theme/`
   * Names must match exactly
3. **Set correct permissions:**

```bash
chown -R www-data:www-data /var/www/pteroca/public/assets/theme/my-theme
chmod -R 755 /var/www/pteroca/public/assets/theme/my-theme
```

4. **Check asset paths in templates:**
   * Ensure theme uses `template_asset()` function
   * Verify file paths are correct

### Theme Causes Errors or Blank Pages

**Symptoms:** Panel shows errors or blank pages after activating theme.

**Immediate fix:**

1. **Switch back to default theme via database:**

```bash
# Connect to database
mysql -u pteroca_user -p pteroca_db

# Update theme setting
UPDATE setting SET value = 'default' WHERE name = 'current_theme';
exit;
```

2. **Clear cache:**

```bash
cd /var/www/pteroca
php bin/console cache:clear
```

3. **Check logs:**

```bash
tail -f var/log/prod.log
```

**Root cause solutions:**

* Contact theme developer with error logs
* Ensure theme is compatible with your PteroCA version
* Verify all theme files are uploaded correctly
* Check PHP error logs for template syntax errors

### Theme Appears Outdated or Incompatible

**Symptoms:** Warning message about theme compatibility.

**Cause:** Theme's `pterocaVersion` requirement is older than your PteroCA installation.

**Solutions:**

1. **Check theme version:**
   * Look for theme updates from developer
   * Verify theme supports your PteroCA version
2. **Update theme:**
   * Download latest version
   * Replace theme files (backup old version first)
   * Test in a staging environment if possible
3. **Use default theme:**
   * Always up-to-date with PteroCA releases
   * Switch back until theme is updated

{% hint style="warning" %}
**Need More Help?**

If you're still experiencing issues:

* Check the [FAQ](/help-and-maintenance/faq.md)
* Review [Troubleshooting Guide](https://github.com/PteroCA-Org/pteroca-homepage/blob/docs/help-and-maintenance/troubleshooting/README.md)
* Ask in the [Discord community](https://discord.com/invite/Gz5phhuZym)
* Contact your theme developer for support
  {% endhint %}

***

## Creating Your Own Themes

If you're a developer interested in creating custom themes for PteroCA, see the complete [**Theme Development Guide**](https://github.com/PteroCA-Org/pteroca-homepage/blob/docs/for-developers/themes/README.md) in the "For Developers" section.

The developer guide includes:

* Theme structure and file organization
* Template.json schema and validation
* Twig templating and template hierarchy
* CSS styling and color customization
* JavaScript integration
* Asset management and compilation
* Testing and debugging themes
* Best practices for theme development

***

## Related Documentation

### Configuration Guides

* [Theme Settings](/customization-and-extensions/themes/theme-settings.md) - Detailed theme settings reference
* [General Settings](/core-configuration/core-configuration/general-settings.md) - Site logo and branding
* [Access Control](/access-and-permissions/access-control/roles-and-permissions.md) - Theme management permissions

### Customization

* [Overview](/customization-and-extensions/customization.md) - General customization options
* [Plugins](/customization-and-extensions/plugins/plugins.md) - Extend functionality with plugins

### Developer Resources

* [Theme Development](https://github.com/PteroCA-Org/pteroca-homepage/blob/docs/for-developers/themes/README.md) - Complete developer guide
* [Twig Documentation](https://twig.symfony.com/doc/3.x/) - Template engine reference

{% hint style="success" %}
**Need Help?**

If you have questions about themes or need assistance:

* Check the [FAQ](/help-and-maintenance/faq.md)
* Review the [Theme Development Guide](https://github.com/PteroCA-Org/pteroca-homepage/blob/docs/for-developers/themes/README.md)
* Join our [Discord community](https://discord.com/invite/Gz5phhuZym)
* Report issues on [GitHub](https://github.com/PteroCA-Org/panel/issues)
  {% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.pteroca.com/customization-and-extensions/themes/themes.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.