# Lios Plugin Contract
Lios plugins are separate `lios-*` executables, not dynamically loaded shared
libraries. A plugin crash therefore cannot corrupt the terminal process, and
core Lios stays small.
## Preferences behavior
The `Plugins` card distinguishes three independent facts:
- installed: Cargo metadata identifies the exact curated registry release;
- enabled: Lios may present and launch that plugin;
- running: a separately launched process may continue until it exits.
Enabling an absent plugin is an explicit install request. Lios invokes Cargo
directly with an argv equivalent to:
```text
cargo install --locked --force --registry crates-io --version =0.1.1 lios-bar
```
No shell command string is built. The catalog supplies the crate name,
executable name, and exact version; user input cannot replace those fields.
Standard output and error are silenced so plugin installation cannot inject
terminal control sequences into the GUI.
After Cargo returns success, Lios requires the discovered executable's adjacent
Cargo root to contain `.crates2.json` metadata matching all of:
- curated crate name;
- exact curated version;
- registry source rather than a local path;
- expected executable name.
A same-named binary without that metadata is shown as unverified and cannot be
launched through Lios until `Repair` installs the pinned registry release.
Disabling changes only `[plugins]` in the Lios config. It never runs
`cargo uninstall`, removes files, deletes plugin data, or terminates a process
that the user already launched. No plugin is installed, repaired, updated, or
launched in the background.
## Configuration
Plugin enablement is stored atomically with user-only config permissions:
```toml
[plugins]
lios_bar = true
```
Malformed non-boolean values fail configuration validation. Unknown
lowercase plugin keys are preserved so a newer Lios release can add catalog
entries without an older release deleting their state.
## Adding an official plugin
A catalog entry must remain a compile-time constant and include a unique
lowercase config key, crates.io package name, executable name, exact reviewed
version, display name, description, and a bounded safe launch contract.
Before catalog inclusion, the plugin must:
- be published under `MIT OR Apache-2.0` with both canonical license files and
explicit Trevor Knott/Knott Dynamics attribution;
- publish a locked crate containing its README and security documentation;
- accept `--version` and `--help` without side effects;
- avoid listening sockets, telemetry, credentials, and automatic downloads
unless those capabilities are the plugin's clearly documented purpose;
- pass formatting, strict Clippy, tests, package verification, and an install
smoke test from the exact public artifact.
Plugins needing destinations, credentials, terminal byte streams, or service
lifecycles require a purpose-built UI and threat model. They must not reuse the
standalone launch contract merely to appear in the catalog.