# Core Concepts

The Concepts section is the mental-model side of Plugin Kit. Each page covers one piece of the runtime's vocabulary: what it is, how it fits with the others, and the design choices behind it. The [reference](https://plugin-kit.saad-ardati.dev/reference/) is for looking up signatures; [guides](https://plugin-kit.saad-ardati.dev/guides/) are for action-oriented walkthroughs; the pages here are for understanding the model that makes the rest cohere.

## How the pieces fit

A **plugin** has an identity and a lifecycle. The runtime decides which plugins are enabled, calls their `register` hook to collect services into the registry, then calls `attach` to start them. **Plugin services** are the classes a plugin owns; the registry stamps identity onto them and injects settings when they resolve.

The **service registry** is where competition happens. Two plugins can register for the same slot; the higher priority wins, and the loser stays reachable as a fallback. **Capabilities** are metadata that travel with each registration so host code can inspect what a slot supports without building anything.

The **event bus** is how plugins coordinate without holding references to each other. Typed events flow in priority order; typed requests fall through handlers until one returns a non-null response. **Event Patterns**, the page next to event bus, covers the patterns for using all of this from inside plugin code rather than the model itself.

The **runtime** owns the global scope and spawns **sessions**. A session is an isolated execution scope with its own registry and bus; opening a second session never disturbs the first. The runtime holds a settings snapshot and exposes a change stream so the host can hand it new `RuntimeSettings` and have it converge.

**Custom contexts** are the optional extension point: when your domain has fields that every plugin in a session should see (the current document, the active user, a tool registry), you subclass `SessionPluginContext` and supply a factory.

## The pages

[Plugins](https://plugin-kit.saad-ardati.dev/concepts/plugins/)
  [Plugin Services](https://plugin-kit.saad-ardati.dev/concepts/plugin-services/)
  [Service Registry](https://plugin-kit.saad-ardati.dev/concepts/service-registry/)
  [Capabilities](https://plugin-kit.saad-ardati.dev/concepts/capabilities/)
  [Configuration](https://plugin-kit.saad-ardati.dev/concepts/configuration/)
  [Event Bus](https://plugin-kit.saad-ardati.dev/concepts/event-bus/)
  [Event Patterns](https://plugin-kit.saad-ardati.dev/concepts/events/)
  [Runtime](https://plugin-kit.saad-ardati.dev/concepts/runtime/)
  [Sessions](https://plugin-kit.saad-ardati.dev/concepts/sessions/)
  [Custom Contexts](https://plugin-kit.saad-ardati.dev/concepts/custom-context/)
The sidebar order is the order most readers find useful (smallest unit outward to the things that move plugins around), but every page links to the others it depends on.

## Where to next

[API reference](https://plugin-kit.saad-ardati.dev/reference/)
  [Guides](https://plugin-kit.saad-ardati.dev/guides/)
  [Architecture](https://plugin-kit.saad-ardati.dev/reference/architecture/)