### Configure Web App Manifest

Source: https://github.com/starcitizentools/mediawiki-skins-citizen/blob/main/docs/src/config/index.md

Enable the web app manifest and customize its properties like colors and icons to allow wiki installation as a standalone app.

```php
$wgCitizenEnableManifest = true;
$wgCitizenManifestOptions = [
    'background_color' => '#0d0e12',
    'description' => '',
    'short_name' => '',
    'theme_color' => "#0d0e12",
    'icons' => [],
];
```

--------------------------------

### GET /api.php?action=appmanifest

Source: https://context7.com/starcitizentools/mediawiki-skins-citizen/llms.txt

Retrieves the PWA web app manifest configuration for the wiki.

```APIDOC
## GET /api.php?action=appmanifest

### Description
Fetches the web app manifest JSON, which defines PWA settings like theme colors, icons, and start URLs for the Citizen skin.

### Method
GET

### Endpoint
/api.php?action=appmanifest&format=json

### Parameters
#### Query Parameters
- **action** (string) - Required - Must be 'appmanifest'
- **format** (string) - Required - Must be 'json'

### Request Example
curl "https://yourwiki.example/api.php?action=appmanifest&format=json"

### Response
#### Success Response (200)
- **name** (string) - The name of the wiki
- **short_name** (string) - Shortened name for the manifest
- **description** (string) - Wiki description
- **start_url** (string) - Default entry point
- **display** (string) - PWA display mode
- **background_color** (string) - Hex color code
- **theme_color** (string) - Hex color code
- **icons** (array) - List of icon objects

#### Response Example
{
  "name": "Your Wiki",
  "short_name": "Wiki",
  "description": "A community wiki",
  "start_url": "/wiki/Main_Page",
  "display": "standalone",
  "background_color": "#0d0e12",
  "theme_color": "#0d0e12",
  "icons": []
}
```

--------------------------------

### Install MediaWiki Citizen Skin

Source: https://github.com/starcitizentools/mediawiki-skins-citizen/blob/main/README.md

This code snippet demonstrates how to load the Citizen skin in your MediaWiki installation. It requires placing the skin files in the skins directory and adding a line to LocalSettings.php.

```php
wfLoadSkin( 'Citizen' );
```

--------------------------------

### Extending the Command Palette

Source: https://github.com/starcitizentools/mediawiki-skins-citizen/blob/main/docs/src/customization/command-palette.md

Provides instructions and a code example for developers on how to add custom entries to the command palette.

```APIDOC
## Extending the Command Palette

### Description
Administrators and developers can enhance the command palette by registering custom entries, enabling shortcuts for external tools, workflows, or redirects.

### Registration Hook
Entries are registered using the `citizen.commandPalette.register` hook.

### JavaScript Example
```javascript
mw.hook( 'citizen.commandPalette.register' ).add( function ( data ) {
    data.register( myEntry );
} );
```

### Custom Entry Examples
- **`/music`**: A command to access music-related features (example site: tagging.wiki).
- **`/kit builder`**: A command that redirects to a kit builder tool (example site: itemasylum.miraheze.org).
- **`/play`**: A command to launch a game (example site: tagging.wiki).
- **`/confetti`**: A command to trigger a confetti effect (example: [MediaWiki:Gadget-Confetti.js](https://starcitizen.tools/MediaWiki:Gadget-Confetti.js#L-17)).
```

--------------------------------

### Registering a Simple Command

Source: https://github.com/starcitizentools/mediawiki-skins-citizen/blob/main/docs/src/customization/command-palette.md

Provides a JavaScript example of how to register a simple command with the command palette. This command is triggered by specific prefixes and executes a direct action upon selection.

```APIDOC
## POST /citizen/commandPalette/register

### Description
Registers a new command or mode with the Citizen command palette.

### Method
POST

### Endpoint
`/citizen/commandPalette/register`

### Parameters
#### Request Body
- **command** (Object) - Required - The command or mode object to register.

### Request Example
```javascript
const myCommand = {
    id: 'my-simple-command',
    triggers: [ '/simple', '/sim' ],
    description: 'Executes a simple action directly.',
    onResultSelect: function ( item ) {
        mw.notify( 'Simple command executed!' );
        return { action: 'none' };
    }
};

mw.hook( 'citizen.commandPalette.register' ).add( function ( data ) {
    data.register( myCommand );
} );
```

### Response
#### Success Response (200)
- **status** (string) - Indicates successful registration.

#### Response Example
```json
{
  "status": "registered"
}
```
```

--------------------------------

### VitePress Script Setup with Dynamic Routing

Source: https://github.com/starcitizentools/mediawiki-skins-citizen/blob/main/docs/src/changelogs/[tag].md

This snippet demonstrates setting up a dynamic route in VitePress using Vue's script setup. It imports necessary functions from 'vitepress', accesses page data, and extracts route parameters to be used by child components. This is useful for creating dynamic pages based on URL parameters.

```vue
<script setup lang="ts">
import { useData } from 'vitepress'
import ChangelogByTag from "@theme/components/ChangelogByTag.vue";

const { page } = useData()
const tag = page.value.params.tag as string
</script>

<!-- markdownlint-disable-file -->
<ChangelogByTag :tag="tag" />
```

--------------------------------

### Install Citizen Skin via Composer

Source: https://github.com/starcitizentools/mediawiki-skins-citizen/blob/main/docs/src/guide/installation.md

Installs the Citizen skin using Composer, a dependency manager for PHP. This method is recommended for managing project dependencies efficiently. It requires running composer commands in the root of your MediaWiki installation.

```sh
COMPOSER=composer.local.json composer require starcitizentools/citizen-skin
composer update --no-dev
```

--------------------------------

### Install and Enable Citizen Skin

Source: https://context7.com/starcitizentools/mediawiki-skins-citizen/llms.txt

Registers the Citizen skin with the MediaWiki engine and sets it as the default theme. It also configures optional Git repository link mapping for version tracking.

```php
wfLoadSkin( 'Citizen' );
$wgDefaultSkin = 'citizen';
$wgGitRepositoryViewers['https://github.com/(.*?)(.git)?'] = 'https://github.com/$1/commit/%H';
```

--------------------------------

### Install Citizen Skin via Git Clone

Source: https://github.com/starcitizentools/mediawiki-skins-citizen/blob/main/docs/src/guide/installation.md

Installs the Citizen skin by cloning the Git repository directly into the skins directory. This method allows for easy tracking of commits and updates via Git. It is suitable for development environments but may include development files not needed for production.

```sh
git clone https://github.com/StarCitizenTools/mediawiki-skins-Citizen.git skins/Citizen
```

--------------------------------

### Command Palette - Registering Custom Modes

Source: https://context7.com/starcitizentools/mediawiki-skins-citizen/llms.txt

This section explains how to register custom search modes that can process sub-queries and return dynamic search results. It includes an example of a 'music search' mode.

```APIDOC
## Command Palette - Registering Custom Modes

Register custom modes that accept sub-queries and return dynamic results.

Modes provide a search context with their own placeholder, icon, and result handling. Triggers must end with a colon.

### Example: Music Search Mode

This example demonstrates registering a custom mode for searching music tracks.

### Method

JavaScript (MediaWiki:Common.js or Gadget)

### Endpoint

N/A (Client-side registration)

### Parameters

N/A

### Request Body

N/A

### Request Example

```javascript
const musicMode = {
    id: 'music-search',
    triggers: [ '/music:', '/m:' ],
    description: 'Search for music tracks',
    placeholder: 'Search music...', 
    emptyState: {
        title: 'Music Search',
        description: 'Type a song name or artist to search'
    },
    noResults: function ( query ) {
        return {
            title: 'No tracks found',
            description: 'Try a different search term for "' + query + '"'
        };
    },
    getResults: function ( subQuery, signal ) {
        if ( !subQuery ) {
            return Promise.resolve( [] );
        }
        return fetch( '/api/music/search?q=' + encodeURIComponent( subQuery ), { signal: signal } )
        .then( response => response.json() )
        .then( data => {
            return data.tracks.map( track => ( {
                id: 'track-' + track.id,
                label: track.title,
                description: track.artist + ' - ' + track.album,
                url: '/wiki/Music:' + track.id,
                type: 'page',
                highlightQuery: true
            } ) );
        } );
    },
    onResultSelect: function ( item ) {
        if ( item.url ) {
            return { action: 'navigate', payload: item.url };
        }
        return { action: 'none' };
    }
};

mw.hook( 'citizen.commandPalette.register' ).add( function ( data ) {
    data.register( musicMode );
} );
```

### Response

N/A (Client-side registration)

### Response Example

N/A
```

--------------------------------

### Register a simple command in Citizen

Source: https://github.com/starcitizentools/mediawiki-skins-citizen/blob/main/docs/src/customization/command-palette.md

Demonstrates how to define a basic command object and register it with the citizen.commandPalette hook. This example uses a simple notify action when the command is selected.

```javascript
const myCommand = {
    id: 'my-simple-command',
    triggers: [ '/simple', '/sim' ],
    description: 'Executes a simple action directly.',
    onResultSelect: function ( item ) {
        mw.notify( 'Simple command executed!' );
        return { action: 'none' };
    }
};

mw.hook( 'citizen.commandPalette.register' ).add( function ( data ) {
    data.register( myCommand );
} );
```

--------------------------------

### Configure Git Repository Viewer in LocalSettings.php

Source: https://github.com/starcitizentools/mediawiki-skins-citizen/blob/main/docs/src/guide/installation.md

Configures MediaWiki to link Git commit IDs to their corresponding pages on GitHub. This is useful when using the Git installation method for skins or extensions, enabling easier navigation to specific commits.

```php
$wgGitRepositoryViewers['https://github.com/(.*?)(.git)?'] = 'https://github.com/$1/commit/%H';
```

--------------------------------

### Add Custom Preference Toggle

Source: https://github.com/starcitizentools/mediawiki-skins-citizen/blob/main/docs/src/customization/preferences.md

An example of adding a new custom toggle switch to the preferences panel under a new section.

```json
{
  "sections": {
    "extensions": {
      "label": "Extensions"
    }
  },
  "preferences": {
    "my-extension-dark-reader": {
      "section": "extensions",
      "type": "switch",
      "options": ["0", "1"],
      "label": "Dark Reader",
      "description": "Enable Dark Reader extension"
    }
  }
}
```

--------------------------------

### Configure PWA Web App Manifest

Source: https://context7.com/starcitizentools/mediawiki-skins-citizen/llms.txt

Enables Progressive Web App functionality, allowing users to install the wiki as a standalone application. Includes settings for manifest colors, names, and icon assets.

```php
$wgCitizenEnableManifest = true;
$wgCitizenManifestOptions = [
    'background_color' => '#0d0e12',
    'theme_color' => '#0d0e12',
    'short_name' => 'MyWiki',
    'description' => 'A community wiki powered by MediaWiki',
    'icons' => [
        ['src' => '/resources/assets/icon-192.png', 'sizes' => '192x192', 'type' => 'image/png'],
        ['src' => '/resources/assets/icon-512.png', 'sizes' => '512x512', 'type' => 'image/png']
    ]
];
```

--------------------------------

### Vue Component for Displaying Changelogs

Source: https://github.com/starcitizentools/mediawiki-skins-citizen/blob/main/docs/src/changelogs/index.md

This script setup imports and utilizes the ChangelogsList component to display release notes. It assumes the component is available in the theme's components directory. No specific inputs or outputs are defined in this snippet, as it's primarily for rendering.

```Vue
<script setup>
import ChangelogsList from "@theme/components/ChangelogsList.vue";
</script>

<ChangelogsList />
```

--------------------------------

### Register Preferences Dynamically with JavaScript API

Source: https://context7.com/starcitizentools/mediawiki-skins-citizen/llms.txt

Dynamically register preferences from gadgets and user scripts using the `citizen.preferences.register` hook. This allows for runtime addition of preferences, following the same schema as the on-wiki JSON configuration. It also includes an example of reacting to preference changes in real-time.

```javascript
// MediaWiki:Gadget-MyGadget.js - Register preferences via JavaScript

// Register custom preference
mw.hook( 'citizen.preferences.register' ).add( function ( register ) {
    register( {
        sections: {
            'my-gadget': {
                label: 'My Gadget Settings'
            }
        },
        preferences: {
            'gadget-enhanced-rc': {
                section: 'my-gadget',
                type: 'switch',
                options: [ '0', '1' ],
                label: 'Enhanced recent changes',
                description: 'Use the enhanced recent changes interface'
            },
            'gadget-font-size': {
                section: 'my-gadget',
                type: 'select',
                options: [
                    { value: 'small', label: 'Small' },
                    { value: 'medium', label: 'Medium' },
                    { value: 'large', label: 'Large' }
                ],
                label: 'Font size',
                description: 'Adjust gadget text size'
            }
        }
    } );
} );

// React to preference changes in real-time
mw.hook( 'citizen.preferences.changed' ).add( function ( featureName, value ) {
    console.log( featureName + ' changed to ' + value );

    if ( featureName === 'gadget-enhanced-rc' ) {
        toggleEnhancedRC( value === '1' );
    }

    if ( featureName === 'gadget-font-size' ) {
        document.documentElement.style.setProperty(
            '--gadget-font-size',
            value === 'small' ? '14px' : value === 'large' ? '18px' : '16px'
        );
    }
} );
```

--------------------------------

### JavaScript Hooks for Citizen Skin Integration

Source: https://context7.com/starcitizentools/mediawiki-skins-citizen/llms.txt

Subscribe to Citizen's mw.hook events to integrate extensions and gadgets. These hooks follow the standard MediaWiki `mw.hook` pattern and support automatic replay for late subscribers. Examples include registering commands in the command palette, registering custom preferences, and listening for preference changes.

```javascript
// Complete hook reference and usage examples

// 1. Register commands/modes in command palette
mw.hook( 'citizen.commandPalette.register' ).add( function ( data ) {
    data.register( {
        id: 'my-command',
        triggers: [ '/mycommand' ],
        description: 'My custom command',
        onResultSelect: function () {
            return { action: 'none' };
        }
    } );
} );

// 2. Register custom preferences
mw.hook( 'citizen.preferences.register' ).add( function ( register ) {
    register( {
        sections: { 'my-section': { label: 'My Section' } },
        preferences: {
            'my-pref': {
                section: 'my-section',
                type: 'switch',
                options: [ '0', '1' ],
                label: 'My Preference'
            }
        }
    } );
} );

// 3. Listen for preference changes
mw.hook( 'citizen.preferences.changed' ).add( function ( featureName, value ) {
    if ( featureName === 'my-pref' ) {
        // Handle preference change
        console.log( 'Preference changed:', value );
    }
} );

// DEPRECATED: Old command palette hook (still works with warning)
// Use 'citizen.commandPalette.register' instead
mw.hook( 'skins.citizen.commandPalette.registerCommand' ).add( function ( data ) {
    data.registerCommand( myCommand ); // Deprecated method
} );
```

--------------------------------

### Execute Composer Preflight in Docker

Source: https://github.com/starcitizentools/mediawiki-skins-citizen/blob/main/AGENTS.md

Command to run the full suite of PHP linting, static analysis, and unit tests within the standard MediaWiki Docker environment.

```bash
docker compose exec mediawiki bash -c "cd /var/www/html/w/skins/Citizen && composer preflight"
```

--------------------------------

### Define Preference Sections

Source: https://github.com/starcitizentools/mediawiki-skins-citizen/blob/main/docs/src/customization/preferences.md

Demonstrates how to define sections for the preferences panel using either an i18n message key or a literal string label.

```json
{
  "sections": {
    "my-section": {
      "labelMsg": "my-extension-section-label"
    }
  }
}
```

```json
{
  "sections": {
    "my-section": {
      "label": "My Section"
    }
  }
}
```

--------------------------------

### Registering Gadget Preferences with mw.hook

Source: https://github.com/starcitizentools/mediawiki-skins-citizen/blob/main/docs/src/customization/preferences.md

Demonstrates how to register custom preferences for a gadget using the `citizen.preferences.register` hook. This allows gadgets to ship their own preference toggles without requiring administrative intervention on wiki configuration.

```javascript
mw.hook( 'citizen.preferences.register' ).add( function ( register ) {
    register( {
        sections: {
            'my-gadget': { label: 'My Gadget' }
        },
        preferences: {
            'gadget-dark-mode': {
                section: 'my-gadget',
                type: 'switch',
                options: [ '0', '1' ],
                label: 'Dark mode',
                description: 'Enable dark mode for this gadget'
            }
        }
    } );
} );
```

```javascript
// Register the preference
mw.hook( 'citizen.preferences.register' ).add( function ( register ) {
    register( {
        sections: {
            gadgets: { label: 'Gadgets' }
        },
        preferences: {
            'gadget-enhanced-rc': {
                section: 'gadgets',
                type: 'switch',
                options: [ '0', '1' ],
                label: 'Enhanced recent changes',
                description: 'Use the enhanced recent changes interface'
            }
        }
    } );
} );
```

--------------------------------

### Enable Interface Features

Source: https://github.com/starcitizentools/mediawiki-skins-citizen/blob/main/docs/src/config/index.md

Toggle collapsible sections, drawer site statistics, and the user preferences panel.

```php
$wgCitizenEnableCollapsibleSections = true;
$wgCitizenEnableDrawerSiteStats = true;
$wgCitizenEnablePreferences = true;
```

--------------------------------

### Command Palette Overview

Source: https://github.com/starcitizentools/mediawiki-skins-citizen/blob/main/docs/src/customization/command-palette.md

Explains the basic functionality of the command palette, including how to open it and its two main entry types: modes and commands.

```APIDOC
## Command Palette

### Description
The command palette provides a fast and efficient way to search for articles and execute actions within the wiki. Users can open it by pressing the `/` key.

### Usage
- Press `/` to open the palette and view all available entries.
- Type characters to filter and search for specific modes or commands.

### Entry Types
- **Modes**: Switch the palette to a different search context (e.g., searching within a specific namespace). The header updates to reflect the current mode, and a back button allows exiting the mode.
- **Commands**: Execute an action immediately upon selection without requiring further input.
```

--------------------------------

### Change Primary Color in Citizen Skin

Source: https://github.com/starcitizentools/mediawiki-skins-citizen/blob/main/docs/src/customization/recipes.md

Adjusts the primary accent color of the Citizen skin using OKLCH hue values. Includes examples for light mode and automatic mode with a media query for dark mode.

```css
:root.skin-theme-clientpref-day {
    --color-progressive-oklch__h: 301.11;
}

@media screen and (prefers-color-scheme: dark) {
    :root.skin-theme-clientpref-os {
        --color-progressive-oklch__h: 301.11;
    }
}
```

--------------------------------

### Set Default Mobile Skin to Citizen

Source: https://github.com/starcitizentools/mediawiki-skins-citizen/blob/main/docs/src/config/extensions.md

This configuration ensures that when accessed from a mobile device, the Citizen skin is used as the default, overriding MobileFrontend's separate mobile experience. This is useful if MobileFrontend is installed but not recommended due to potential conflicts.

```php
$wgDefaultMobileSkin = 'citizen';
```

--------------------------------

### Fetch Latest Release and Redirect

Source: https://github.com/starcitizentools/mediawiki-skins-citizen/blob/main/docs/src/changelogs/latest.md

This script uses the Octokit library to query the GitHub API for the latest repository release. Upon successful retrieval, it navigates the user to the specific changelog page; otherwise, it falls back to the main changelogs index.

```typescript
import { onMounted } from 'vue'
import { useRouter, withBase } from 'vitepress'
import { Octokit } from '@octokit/rest'
import { GITHUB_OWNER, GITHUB_REPO } from '../../.vitepress/constants'

const router = useRouter()

onMounted(async () => {
  try {
    const octokit = new Octokit( { auth: import.meta.env.GITHUB_TOKEN } )
    const { data } = await octokit.repos.listReleases({
      owner: GITHUB_OWNER,
      repo: GITHUB_REPO,
      per_page: 1,
    })

    if (data && data.length > 0 && data[0].tag_name) {
      const latestTag = data[0].tag_name
      router.go(withBase(`/changelogs/${latestTag}`))
    } else {
      router.go(withBase('/changelogs/'))
    }
  } catch (error) {
    console.error('Failed to fetch latest release:', error)
    router.go(withBase('/changelogs/'))
  }
})
```

--------------------------------

### PHP Extension Configuration for Citizen

Source: https://context7.com/starcitizentools/mediawiki-skins-citizen/llms.txt

Configure recommended PHP extensions in LocalSettings.php to enhance Citizen MediaWiki skin functionality. These extensions provide features like search result thumbnails, article descriptions, and Semantic MediaWiki integration.

```php
// LocalSettings.php - Extension configuration for Citizen

// PageImages: Adds thumbnails to command palette results
// (bundled with MediaWiki, just enable it)
wfLoadExtension( 'PageImages' );

// TextExtracts: Adds descriptions to command palette results
wfLoadExtension( 'TextExtracts' );
$wgExtractsExtendRestSearch = true;

// ShortDescription: Display descriptions under page titles
wfLoadExtension( 'ShortDescription' );

// RelatedArticles: Show related pages in command palette
wfLoadExtension( 'RelatedArticles' );
$wgRelatedArticlesFooterAllowedSkins[] = 'citizen';

// MobileFrontend (if needed - not recommended)
wfLoadExtension( 'MobileFrontend' );
$wgDefaultMobileSkin = 'citizen';

// TemplateStylesExtender: Enable CSS variables in TemplateStyles
wfLoadExtension( 'TemplateStylesExtender' );

// Semantic MediaWiki: Adds /smw: mode to command palette
// (auto-detected when SMW is installed)
```

--------------------------------

### On-wiki JSON Configuration

Source: https://github.com/starcitizentools/mediawiki-skins-citizen/blob/main/docs/src/customization/preferences.md

This section details how to configure Citizen preferences by creating a JSON file on your MediaWiki instance at `MediaWiki:Citizen-preferences.json`.

```APIDOC
## On-wiki JSON Configuration

### Description
Configure Citizen preferences by creating a JSON file at `MediaWiki:Citizen-preferences.json`. This allows site-wide customization managed by administrators.

### Method
Create or edit the page `MediaWiki:Citizen-preferences.json` on your wiki.

### Endpoint
N/A (On-wiki configuration)

### Parameters
#### Request Body
- **sections** (object) - Optional - Defines the sections for grouping preferences.
  - **section-key** (object) - Represents a single section.
    - **labelMsg** (string) - Optional - i18n message key for the section label.
    - **label** (string) - Optional - Literal string for the section label.
- **preferences** (object) - Optional - Defines the individual preferences.
  - **preference-key** (object or null) - Represents a single preference or null to remove it.
    - **section** (string) - Required - The key of the section this preference belongs to.
    - **type** (string) - Optional - The type of preference (e.g., "switch", "select", "radio"). Auto-detected if omitted.
    - **options** (array) - Required - Defines the available options for the preference. Can be a short form `["0", "1"]` or a long form `[{"value": "0", "labelMsg": "..."}]`.
    - **labelMsg** (string) - Optional - i18n message key for the preference label.
    - **label** (string) - Optional - Literal string for the preference label.
    - **descriptionMsg** (string) - Optional - i18n message key for the preference description.
    - **description** (string) - Optional - Literal string for the preference description.
    - **columns** (number) - Optional - For radio type, specifies the number of columns (default: 2).

### Request Example
```json
{
  "sections": {
    "extensions": {
      "label": "Extensions"
    }
  },
  "preferences": {
    "my-extension-dark-reader": {
      "section": "extensions",
      "type": "switch",
      "options": ["0", "1"],
      "label": "Dark Reader",
      "description": "Enable Dark Reader extension"
    }
  }
}
```

### Response
#### Success Response (200)
Configuration is applied directly by the wiki. No explicit API response.

#### Response Example
N/A
```

--------------------------------

### JavaScript API Configuration

Source: https://github.com/starcitizentools/mediawiki-skins-citizen/blob/main/docs/src/customization/preferences.md

This section explains how to register preferences programmatically using JavaScript within gadgets or user scripts via `mw.hook`.

```APIDOC
## JavaScript API Configuration

### Description
Register preferences from any gadget or user script using `mw.hook`. This method uses the same configuration schema as the on-wiki JSON method.

### Method
Use `mw.hook('Citizen.preferences').add(callback)` to register preferences.

### Endpoint
N/A (Client-side scripting)

### Parameters
#### Request Body
- **sections** (object) - Optional - Defines the sections for grouping preferences.
  - **section-key** (object) - Represents a single section.
    - **labelMsg** (string) - Optional - i18n message key for the section label.
    - **label** (string) - Optional - Literal string for the section label.
- **preferences** (object) - Optional - Defines the individual preferences.
  - **preference-key** (object) - Represents a single preference.
    - **section** (string) - Required - The key of the section this preference belongs to.
    - **type** (string) - Optional - The type of preference (e.g., "switch", "select", "radio"). Auto-detected if omitted.
    - **options** (array) - Required - Defines the available options for the preference. Can be a short form `["0", "1"]` or a long form `[{"value": "0", "labelMsg": "..."}]`.
    - **labelMsg** (string) - Optional - i18n message key for the preference label.
    - **label** (string) - Optional - Literal string for the preference label.
    - **descriptionMsg** (string) - Optional - i18n message key for the preference description.
    - **description** (string) - Optional - Literal string for the preference description.
    - **columns** (number) - Optional - For radio type, specifies the number of columns (default: 2).

### Request Example
```javascript
mw.hook('Citizen.preferences').add(function(prefs) {
  prefs.add({
    sections: {
      "my-custom-section": {
        "label": "My Custom Settings"
      }
    },
    preferences: {
      "my-custom-toggle": {
        "section": "my-custom-section",
        "type": "switch",
        "options": ["0", "1"],
        "label": "Enable My Feature",
        "description": "Toggles my custom feature."
      }
    }
  });
});
```

### Response
#### Success Response (200)
Preferences are registered client-side. No explicit API response.

#### Response Example
N/A
```

--------------------------------

### Handling Command Palette Action Results

Source: https://context7.com/starcitizentools/mediawiki-skins-citizen/llms.txt

Explains the different action types available when a user selects a result from the command palette. It shows how to return specific action objects to control navigation, query updates, or palette behavior.

```javascript
const actionExamples = {
    id: 'action-examples',
    triggers: [ '/actions:' ],
    description: 'Demonstrate action types',
    getResults: function ( subQuery ) {
        return Promise.resolve( [
            { id: 'stay', label: 'Stay in palette', type: 'action' },
            { id: 'navigate', label: 'Go to Main Page', type: 'action' },
            { id: 'exit-query', label: 'Exit with query', type: 'action' },
            { id: 'update', label: 'Update current query', type: 'action' }
        ] );
    },
    onResultSelect: function ( item ) {
        switch ( item.id ) {
            case 'stay':
                mw.notify( 'Action executed!' );
                return { action: 'none' };
            case 'navigate':
                return {
                    action: 'navigate',
                    payload: mw.util.getUrl( 'Main_Page' )
                };
            case 'exit-query':
                return {
                    action: 'exitWithQuery',
                    payload: 'Template:'
                };
            case 'update':
                return {
                    action: 'updateQuery',
                    payload: 'updated search term'
                };
        }
    }
};
mw.hook( 'citizen.commandPalette.register' ).add( function ( data ) {
    data.register( actionExamples );
} );
```

--------------------------------

### Preferences Panel - JavaScript API

Source: https://context7.com/starcitizentools/mediawiki-skins-citizen/llms.txt

Register preferences dynamically from gadgets and user scripts using the `citizen.preferences.register` hook. This allows for runtime registration of preferences with the same schema as the on-wiki JSON configuration.

```APIDOC
## Preferences Panel - JavaScript API

### Description
Dynamically register new preferences or preference sections from JavaScript, such as within gadgets or user scripts. The registration process uses the `citizen.preferences.register` hook and accepts a configuration object identical to the on-wiki JSON format.

### Method
`mw.hook( 'citizen.preferences.register' ).add( function ( register ) { ... } );`
`mw.hook( 'citizen.preferences.changed' ).add( function ( featureName, value ) { ... } );`

### Parameters
#### `citizen.preferences.register` Hook
- **register** (function) - A function provided by the hook to register preference configurations.
  - Accepts a configuration object with `sections` and `preferences` properties, mirroring the JSON schema.

#### `citizen.preferences.changed` Hook
- **featureName** (string) - The name of the preference that was changed.
- **value** (string) - The new value of the preference.

### Request Example (Registering Preferences)
```javascript
// MediaWiki:Gadget-MyGadget.js - Register preferences via JavaScript

mw.hook( 'citizen.preferences.register' ).add( function ( register ) {
    register( {
        sections: {
            'my-gadget': {
                label: 'My Gadget Settings'
            }
        },
        preferences: {
            'gadget-enhanced-rc': {
                section: 'my-gadget',
                type: 'switch',
                options: [ '0', '1' ],
                label: 'Enhanced recent changes',
                description: 'Use the enhanced recent changes interface'
            },
            'gadget-font-size': {
                section: 'my-gadget',
                type: 'select',
                options: [
                    { value: 'small', label: 'Small' },
                    { value: 'medium', label: 'Medium' },
                    { value: 'large', label: 'Large' }
                ],
                label: 'Font size',
                description: 'Adjust gadget text size'
            }
        }
    } );
} );
```

### Request Example (Reacting to Changes)
```javascript
// MediaWiki:Gadget-MyGadget.js - React to preference changes

mw.hook( 'citizen.preferences.changed' ).add( function ( featureName, value ) {
    console.log( featureName + ' changed to ' + value );

    if ( featureName === 'gadget-enhanced-rc' ) {
        toggleEnhancedRC( value === '1' );
    }

    if ( featureName === 'gadget-font-size' ) {
        document.documentElement.style.setProperty(
            '--gadget-font-size',
            value === 'small' ? '14px' : value === 'large' ? '18px' : '16px'
        );
    }
} );
```
```

--------------------------------

### Configure Citizen Skin Appearance

Source: https://github.com/starcitizentools/mediawiki-skins-citizen/blob/main/docs/src/config/index.md

Settings to control the header position, default theme, and page tool visibility for the Citizen skin.

```php
$wgCitizenHeaderPosition = 'left';
$wgCitizenThemeDefault = 'auto';
$wgCitizenShowPageTools = true;
```

--------------------------------

### Configuration Schema Reference

Source: https://github.com/starcitizentools/mediawiki-skins-citizen/blob/main/docs/src/customization/preferences.md

Detailed reference for the configuration schema used for both on-wiki JSON and JavaScript API preferences.

```APIDOC
## Configuration Schema Reference

### Description
This document outlines the schema for configuring Citizen preferences, applicable to both on-wiki JSON and JavaScript API methods.

### Sections Schema
Sections are used to group related preferences. Each section requires either an i18n message key or a literal label.

#### Using i18n message key:
```json
{
  "sections": {
    "my-section": {
      "labelMsg": "my-extension-section-label"
    }
  }
}
```

#### Using literal label:
```json
{
  "sections": {
    "my-section": {
      "label": "My Section"
    }
  }
}
```

### Preference Entries Schema
Each preference is defined by a key (its feature name) and includes details about its section, type, and display text.

```json
{
  "preferences": {
    "my-feature": {
      "section": "my-section",
      "type": "switch",
      "options": ["0", "1"],
      "labelMsg": "my-feature-name",
      "descriptionMsg": "my-feature-description"
    }
  }
}
```

### Field Reference

| Field | Type | Description |
| :--- | :--- | :--- |
| `section` | string | Which section this preference belongs to. |
| `type` | string | "switch", "select", or "radio". Auto-detected if omitted (2 options = switch, 3+ = select). |
| `options` | array | Short form `["0", "1"]` or long form `[{"value": "0", "labelMsg": "..."}]`. |
| `labelMsg` / `label` | string | i18n message key or literal text for the preference name. |
| `descriptionMsg` / `description` | string | i18n message key or literal text for the description. |
| `columns` | number | For radio type, number of columns (default: 2). |

### `label` vs `labelMsg`

- **`labelMsg`** (and `descriptionMsg`): References an i18n message key. Use for multilingual wikis.
- **`label`** (and `description`): A literal string. Use for single-language wikis or quick prototyping.
```

--------------------------------

### Built-in Entries and Aliases

Source: https://github.com/starcitizentools/mediawiki-skins-citizen/blob/main/docs/src/customization/command-palette.md

Lists the default modes and commands available in the command palette, along with their triggers and aliases.

```APIDOC
## Built-in Entries

### Description
The command palette comes with several pre-defined entries for common tasks and navigation.

### Entries Table
| Trigger | Alias | Type | Description |
| :--- | :--- | :--- | :--- |
| `/` | - | - | Show all available modes and commands. |
| `/ns:` | `:` | Mode | Browse and select a namespace. |
| `/action:` | `>` | Mode | Search for actions and special pages. |
| `/user:` | `@` | Mode | Search for a user. |
| `/smw:` | - | Mode | Query pages with Semantic MediaWiki Ask syntax. Only available when SMW is installed. |

### Instant Mode Entry
Single-character aliases like `:`, `>`, and `@` can be used directly to enter their respective modes without the `/` prefix.
```

--------------------------------

### Modify Existing Preference Options

Source: https://github.com/starcitizentools/mediawiki-skins-citizen/blob/main/docs/src/customization/preferences.md

Shows how to override the options array for an existing preference, such as the skin theme.

```json
{
  "preferences": {
    "skin-theme": {
      "options": [
        { "value": "day", "labelMsg": "citizen-theme-day-label" },
        { "value": "night", "labelMsg": "citizen-theme-night-label" }
      ],
      "columns": 2
    }
  }
}
```

--------------------------------

### Reacting to Preference Changes with mw.hook

Source: https://github.com/starcitizentools/mediawiki-skins-citizen/blob/main/docs/src/customization/preferences.md

Shows how to listen for changes in user preferences using the `citizen.preferences.changed` hook. This enables gadgets to react dynamically when a user toggles a preference, allowing for immediate UI updates or feature activation.

```javascript
// React to changes
mw.hook( 'citizen.preferences.changed' ).add( function ( featureName, value ) {
    if ( featureName === 'gadget-enhanced-rc' ) {
        toggleEnhancedRC( value === '1' );
    }
} );
```

```javascript
mw.hook( 'citizen.preferences.changed' ).add( function ( featureName, value ) {
    console.log( featureName + ' changed to ' + value );
} );
```

--------------------------------

### Configure Typography and CSS Overrides

Source: https://github.com/starcitizentools/mediawiki-skins-citizen/blob/main/docs/src/config/index.md

Manage font loading for specific scripts and define CSS classes for container behavior.

```php
$wgCitizenEnableARFonts = false;
$wgCitizenEnableCJKFonts = false;
$wgCitizenOverflowInheritedClasses = [ 'floatleft', 'floatright' ];
$wgCitizenOverflowNowrapClasses = [ 'noresize', 'citizen-table-nowrap', 'cargoDynamicTable', 'dataTable', 'smw-datatable', 'srf-datatable' ];
```

--------------------------------

### Entry Properties

Source: https://github.com/starcitizentools/mediawiki-skins-citizen/blob/main/docs/src/customization/command-palette.md

Defines the properties required for each entry (command or mode) in the command palette. Entries must have an `id`, `triggers`, and `description`. Modes also support `placeholder`, `icon`, `getResults`, `onResultSelect`, `emptyState`, `noResults`, and `tokenPattern`.

```APIDOC
## Entry Properties

Every entry must have at minimum an `id`, `triggers`, and `description`. If the entry provides a `getResults` function, it becomes a **mode**. Without `getResults`, it's a **command**.

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `id` | `string` | Yes | Unique identifier. |
| `triggers` | `string[]` | Yes | Prefixes that activate this entry. Triggers ending with `:` accept a sub-query. |
| `description` | `string` | Yes | Short explanation shown in the command list. |
| `placeholder` | `string` | No | Input placeholder when mode is active (e.g., "Search users"). Modes only. |
| `icon` | `Object` | No | Codex icon for the header when mode is active. Modes only. |
| `getResults` | `function` | No | `(subQuery, signal?, tokens?) => Promise<Array>` — if provided, this entry is a mode. An optional `AbortSignal` and the current token array are passed as additional arguments. |
| `onResultSelect` | `function` | No | `(item) => { action, payload }` — handles selection of a result item. |
| `emptyState` | `Object` | No | `{ title, description, icon }` — content shown when the mode is active with no query. Falls back to default search messaging. Modes only. |
| `noResults` | `function` | No | `(query, tokens?) => { title, description, icon }` — returns content shown when a query produces no results. Falls back to default no-results messaging. Modes only. |
| `tokenPattern` | `Object` | No | Token detection pattern for auto-tokenization. See [token patterns](#token-patterns). Modes only. |
```

--------------------------------

### API Access to Web App Manifest

Source: https://context7.com/starcitizentools/mediawiki-skins-citizen/llms.txt

Access the web app manifest configuration for the Citizen skin via the MediaWiki API. This allows programmatic retrieval of PWA manifest details, such as name, short name, description, and display settings.

```bash
# Fetch the web app manifest via API
curl "https://yourwiki.example/api.php?action=appmanifest&format=json"

# Response example:
# {
#   "name": "Your Wiki",
#   "short_name": "Wiki",
#   "description": "A community wiki",
#   "start_url": "/wiki/Main_Page",
#   "display": "standalone",
#   "background_color": "#0d0e12",
#   "theme_color": "#0d0e12",
#   "icons": [...]
```

--------------------------------

### Apply CSS Styling Based on User Preferences

Source: https://context7.com/starcitizentools/mediawiki-skins-citizen/llms.txt

Style elements in the MediaWiki Citizen skin by leveraging CSS classes added to the `<html>` element. These classes follow the format `<feature>-clientpref-<value>`, allowing targeted styling based on user-selected preferences for features like dark mode or layout density.

```css
/* MediaWiki:Common.css - Style based on custom preferences */

/* Target when dark reader compatibility is enabled */
html.my-extension-dark-reader-clientpref-1 {
    /* Adjust colors for Dark Reader compatibility */
    --color-surface-0: var(--color-surface-1);
}

/* Target layout density preferences */
html.my-layout-style-clientpref-compact .mw-body {
    padding: 0.5rem;
    line-height: 1.4;
}

html.my-layout-style-clientpref-comfortable .mw-body {
    padding: 1rem;
    line-height: 1.6;
}

html.my-layout-style-clientpref-spacious .mw-body {
    padding: 2rem;
    line-height: 1.8;
}

/* Performance mode hooks */
.citizen-feature-performance-mode-clientpref-0 .my-fancy-element {
    backdrop-filter: blur( 16px );
    transition: all 0.3s ease;
}

.citizen-feature-performance-mode-clientpref-1 .my-fancy-element {
    background-color: var( --color-surface-1 );
    transition: none;
}

/* Animation readiness - prevent jank on first paint */
.citizen-animations-ready .my-element {
    transition: opacity var( --transition-duration-medium );
}
```

--------------------------------

### Migrating Command Registration API

Source: https://github.com/starcitizentools/mediawiki-skins-citizen/blob/main/docs/src/customization/command-palette.md

Demonstrates the transition from the deprecated 'skins.citizen.commandPalette.registerCommand' hook to the new 'citizen.commandPalette.register' hook.

```javascript
// Before
mw.hook( 'skins.citizen.commandPalette.registerCommand' ).add( function ( data ) {
    data.registerCommand( myCommand );
} );

// After
mw.hook( 'citizen.commandPalette.register' ).add( function ( data ) {
    data.register( myCommand );
} );
```

--------------------------------

### Semantic MediaWiki Integration

Source: https://github.com/starcitizentools/mediawiki-skins-citizen/blob/main/docs/src/customization/command-palette.md

Explains the functionality of the `/smw:` mode for querying Semantic MediaWiki data.

```APIDOC
## Semantic MediaWiki Mode (`/smw:`) 

### Description
This mode is available when Semantic MediaWiki (SMW) is installed and allows users to run SMW Ask queries interactively within the command palette.

### Usage
- Type SMW Ask query conditions, such as `[[Category:City]]` or `[[Located in::Germany]]`.
- Each completed condition is displayed as a token chip.
- Results show pages matching the current query.

### Chaining Conditions
Multiple conditions can be chained together, with each chip further refining the query, similar to standard SMW Ask queries.

### Availability
This mode is loaded and registered only if SMW is detected on the wiki.
```

--------------------------------

### Token Patterns

Source: https://github.com/starcitizentools/mediawiki-skins-citizen/blob/main/docs/src/customization/command-palette.md

Explains how to define `tokenPattern` for modes to enable auto-tokenization, converting matched text into chips. Details the properties of a token pattern object.

```APIDOC
## Token Patterns

Modes can declare a `tokenPattern` to enable auto-tokenization — when the user's input matches the pattern, the matched text is converted into a chip. This is how the namespace mode turns `Talk:` into a chip, and how the SMW mode turns `[[Category:City]]` into one.

| Property | Type | Description |
| :--- | :--- | :--- |
| `modeId` | `string` | Identifies which mode owns this token. |
| `position` | `'prefix' | 'any'` | Where tokens can appear — `prefix` means only at the start, `any` means anywhere in the input. |
| `activeIn` | `string` | Which mode context this pattern is active in (`'root'` for default search, or a mode id like `'smw'`). |
| `match` | `function` | `(text) => { label, raw } | null` — tests whether the text starts with a tokenizable pattern. Returns `label` (display text) and `raw` (the original text) on match, or `null`. |

Tokens are passed to `getResults` and `noResults` so modes can incorporate them into queries. For example, the SMW mode reconstructs the full Ask query from its token chips plus any free text.
```

--------------------------------

### Mode Behavior and Tokenized Input

Source: https://github.com/starcitizentools/mediawiki-skins-citizen/blob/main/docs/src/customization/command-palette.md

Details the user experience when entering a mode within the command palette, including UI changes and input handling.

```APIDOC
## Mode Behavior

### Description
When a user enters a mode in the command palette, the interface adapts to provide context-specific search capabilities.

### UI Changes
- The search icon changes to reflect the current mode.
- The placeholder text updates to guide the user (e.g., "Search users").
- A back button appears, allowing the user to exit the current mode.

### Escape Key Behavior
The Escape key follows a three-step pattern:
1. Clears the current query.
2. Exits the current mode.
3. Closes the command palette.

### Tokenized Input
Some modes support tokenized input, where parts of the query are visually represented as chips. For example, typing a namespace prefix like `Talk:` converts it into a chip, allowing further input to search within that specific namespace. Pressing backspace on an empty input removes the last chip.
```

--------------------------------

### Managing Transitions with Animation Readiness Class

Source: https://github.com/starcitizentools/mediawiki-skins-citizen/blob/main/docs/src/customization/performance-mode.md

This CSS code snippet shows how to ensure CSS transitions are applied correctly after the skin's JavaScript has loaded. The '.citizen-animations-ready' class is added to the root element by the Citizen skin's JavaScript. By gating transitions under this class, developers can prevent visual 'jank' during the initial page load and ensure smooth animations only when the system is ready.

```css
.citizen-animations-ready .my-element {
  transition: opacity var( --transition-duration-medium );
}
```