# Chi concepts

Chi is a family of modular Pi coding-agent extensions. These are the terms used
by Chi Base and Chi modules.

- **Chi module** — A separate Pi extension that registers one focused capability
  with Chi Base.
- **Chi Base** — The shared Pi extension that discovers modules, owns the live
  registry, initializes dependencies, and persists module configuration.
- **Pi extension** — A package loaded by Pi through `ExtensionAPI`. Chi modules
  are Pi extensions; Chi Base is one too.
- **Discovery** — The `chi:discover` event. A module listens for it and calls
  `chi.register(...)` during the registration phase.
- **Registry** — The live `ChiBase` object delivered through discovery. It is
  the direct API for registration, dependency access, status, and configuration.
- **Module definition** — The object passed to `register`, containing the
  module ID, release version, dependencies, API, configuration contract, and
  initializer.
- **Module ID** — A stable, unique registry key such as `chi-example`. Duplicate
  registrations fail closed; neither conflicting module initializes.
- **Module API** — The small object a module exposes to other modules through
  `chi.get` or `chi.require`.
- **Dependency** — Another module ID that must be ready before this module's
  `initialize` function runs. Missing or failed dependencies block dependents.
- **Initialization** — The once-per-session lifecycle callback that starts a
  module with its parsed configuration.
- **Configuration contract** — A Zod object schema and schema version declared
  by a module. It defines persisted values and editable settings.
- **Config change callback** — The optional `onConfigChange(chi, current,
  changes)` lifecycle hook a module uses to synchronize retained runtime state
  after its effective configuration changes. It is awaited and does not rerun
  initialization.
- **Configuration scope** — `global` settings apply everywhere; `project`
  settings apply only in a trusted project and override global values.
- **Migration** — A module-provided function that converts older persisted
  configuration data to its current schema version.
- **Chi setting** — A top-level required enum or defaulted string field. These
  fields are exposed by the `/chi` settings command.
- **Module status** — Registry state for diagnostics: registered, initializing,
  ready, blocked, or failed.
- **Trusted project** — A project Pi has marked trusted, allowing Chi Base to
  read and write project-scoped configuration. When loaded project overrides
  exist, `/chi` opens in project scope first.

See [how to write a Chi module](docs/how-to-write-a-chi-module.md) for the
smallest working implementation.