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

# Plugin Manifest

> Reference for the @PluginManifest annotation

Every Klyx extension must declare a plugin entry class annotated with `@PluginManifest`. The Klyx Kotlin compiler plugin reads this annotation at compile time, validates it, and generates the `plugin.json` descriptor and a `PluginDescriptor` companion property for you automatically.

You never hand-author `plugin.json` — it is generated from the annotation.

## Declaration

Annotate your `KlyxPlugin` implementation class:

```kotlin theme={null}
package com.myext

@PluginManifest(
    id = "com.myext.helloworld",
    version = "1.0.0",
    name = "Hello World",
    minAppVersion = "4.2.0",
    description = "A minimal Klyx extension",
    author = Author(name = "Your Name"),
    license = "MIT",
    links = Links(
        source = "https://github.com/you/my-extension",
        issues = "https://github.com/you/my-extension/issues"
    ),
    permissions = []
)
class MyExtension : KlyxPlugin {
    override suspend fun onLoad() { /* ... */ }
    override suspend fun onStart() { /* ... */ }
    override suspend fun onStop() { /* ... */ }
    override suspend fun onUnload() { /* ... */ }
}
```

## Author annotation

The `Author` annotation provides information about the plugin's author:

```kotlin theme={null}
@Author(
    name = "Your Name",
    email = "you@example.com",
    url = "https://example.com",
    github = "yourhandle"
)
```

## Links annotation

The `Links` annotation provides useful links associated with the extension:

```kotlin theme={null}
@Links(
    source = "https://github.com/you/my-extension",
    issues = "https://github.com/you/my-extension/issues",
    website = "https://example.com",
    donate = "https://ko-fi.com/you"
)
```

## Field reference

### `id` (required)

Unique plugin identifier in reverse-DNS notation. Must match the regex pattern of lowercase letters, digits, dots, and hyphens, starting with a letter.

```
"com.myext.helloworld"
```

### `version` (default: `"0.1.0"`)

Semantic version string. Klyx uses this to determine if an update is available.

```
"1.0.0"
```

### `name` (default: `"<auto>"`, falls back to `id`)

Human-readable display name shown in Klyx's plugin manager. If left blank or set to `"<auto>"`, it defaults to the `id`.

```
"Hello World"
```

### `minAppVersion` (default: `"4.2.0"`)

The minimum version of Klyx required to run this extension. Must be a valid semver string. Version `4.2.0` introduced the plugin system.

```
"4.2.0"
```

### `maxAppVersion` (default: `""`, meaning no upper limit)

If set, the extension will not load on newer versions of Klyx. Use this when a Klyx major version breaks your extension's API. Must be a valid semver string if non-empty.

```
"5.0.0"
```

### `description` (default: `""`)

A short description of what the extension does.

```
"Adds custom features to Klyx"
```

### `icon` (default: `""`)

Path (relative to the project root) to the plugin's icon file. The Gradle plugin can auto-detect `icon.png` or `icon.jpg` from the project root if this is left blank.

```
"icon.png"
```

### `license` (default: `""`)

SPDX license identifier or a short license name.

```
"MIT"
```

### `author` (default: `Author(name = "")`)

Information about the extension author. See the `Author` annotation above. The `name` field is required if the `author` annotation is present.

### `links` (default: `Links()`)

Useful links related to the extension. See the `Links` annotation above. All fields are optional.

### `permissions` (default: `[]`)

A list of permission strings the extension requires. Currently reserved for future use.

```
["terminal", "network"]
```

## Compile-time validation

The Klyx compiler plugin validates the `@PluginManifest` annotation at compile time and reports errors as compile errors (not runtime failures). It checks:

| Rule                  | Details                                                       |
| --------------------- | ------------------------------------------------------------- |
| Plugin ID format      | Must match reverse-DNS pattern (e.g. `com.example.git-tools`) |
| Version format        | Must be valid semver (e.g. `1.0.0`)                           |
| minAppVersion         | Must be valid semver                                          |
| maxAppVersion         | If set, must be valid semver                                  |
| min/max order         | `minAppVersion` must not be greater than `maxAppVersion`      |
| Annotation target     | Must be on a class, not a function or property                |
| KlyxPlugin            | The annotated class must implement `KlyxPlugin`               |
| Constructor           | Must have a public no-argument constructor                    |
| Class modifiers       | Must not be abstract, inner, or local                         |
| Duplicate             | Only one class per module can be annotated                    |
| `descriptor` property | The name `descriptor` is reserved on the companion object     |

## Generated artifacts

After compilation, the following is generated in `build/klyx/generated/`:

1. **`plugin.json`** — A JSON file consumed by the Klyx Gradle plugin when assembling the `.klyx` bundle
2. **`PluginDescriptor` companion property** — Accessible as `MyExtension.descriptor`, this is a `PluginDescriptor` instance that the `PluginManager` can read at runtime for integrity verification. The compiled descriptor is compared against the `plugin.json` from the bundle to detect tampering or corruption.

## Example

Here is an example of using `@PluginManifest` on a plugin entry class:

```kotlin theme={null}
@PluginManifest(
    id = "com.example.myplugin",
    version = "1.0.0",
    name = "My Plugin",
    minAppVersion = "4.2.0",
    description = "A comprehensive reference implementation demonstrating all Klyx extension APIs",
    author = Author(name = "Klyx"),
    license = "MIT",
    links = Links(
        source = "https://github.com/klyx-dev/my-plugin",
        issues = "https://github.com/klyx-dev/my-plugin/issues"
    ),
    permissions = []
)
class MyPlugin : KlyxPlugin { /* ... */ }
```