# Contributing

Ekklesia is being built in verified, reviewable phases. Changes should preserve the dependency
boundaries described in [repository-boundaries.md](docs/architecture/repository-boundaries.md).

Before opening a change, run:

```bash
pnpm verify
```

Migration-runner changes also require the disposable live PostgreSQL suite:

```bash
pnpm test:migrations:integration
```

See the [testing guide](docs/development/testing.md) for the distinction between unit and live
evidence and for credential-safe troubleshooting.

When adding or changing a module manifest, also run `pnpm modules:validate` directly for focused,
path-aware discovery errors. It is included in `pnpm verify`.

If Docker is available, also validate the development infrastructure:

```bash
pnpm infrastructure:config
```

## Package rules

- Use strict TypeScript for production packages.
- Expose supported entry points through package `exports`; do not import another package's
  private source paths.
- Use `workspace:` ranges for internal package dependencies.
- Modules own their own UI and author it in React and TypeScript (ADR 0022). A module package may
  contain `.tsx` and depend on `react`, `react-dom`, and `@ekklesia/module-ui-sdk`. Every other UI
  framework, `.jsx`, stylesheets, and other presentation formats remain rejected by
  `pnpm boundaries`. UI source lives at `src/ui/index.tsx` and `pnpm build` compiles it to the
  artifact the manifest declares, via `@ekklesia/module-ui-build` (ADR 0023) — module authors write
  no bundler configuration. Styling is React inline style objects only for now, and no host mounts a
  UI entrypoint yet.
- Module UI reaches its host only through `@ekklesia/module-ui-sdk`, and asks the host for its own
  API by relative path — never by constructing `/api/v1/modules/<id>/...`, which is Ekklesia's
  private deployment detail and would break standalone hosting.
- The containing application shell, navigation, global theme, and platform policy belong to Core and
  the host application, never to a module.
- Add or update tests when changing a contract or architectural rule.
- Record major architectural changes in an ADR rather than burying them in an implementation.

Runtime registries and aggregate schemas will be produced by later phases. Do not add a manually
maintained feature-module registry; discovery starts from validated `ekklesia.module.json` files.