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

# Contributing

> Build, test, and extend Blue and its public documentation.

## Development checks

Run `scripts/setup.sh` once per clone to install the Lefthook checks for staged Rust, dashboard and website TypeScript, and OpenAPI contract changes. Run the documentation checks below for MDX changes.

```bash theme={null}
cargo build --workspace
cargo test --workspace
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
```

Dashboard checks run from `apps/dashboard`:

```bash theme={null}
npm ci
npm test
npm run lint
npm run build
```

### Dashboard UI

The dashboard uses the stock shadcn/ui `base-nova` preset initialized with shadcn CLI 4.19.0, Tailwind CSS v4, Base UI primitives, CSS-variable theming, Geist, and Lucide icons. `apps/dashboard/components.json` is the registry configuration.

Add UI primitives through the current CLI from `apps/dashboard`:

```bash theme={null}
npx shadcn@latest add dialog
```

Use generated components from `@/components/ui` and Tailwind utilities in routes. Keep product composition in `app` or non-`ui` components, and avoid restoring global element styles that override the stock shadcn component variants.

Documentation checks run from `apps/docs`:

```bash theme={null}
npm ci
npm run check:content
npm run check:contract
npm run validate
npm run links
```

## Keep contracts synchronized

`deploy/contract/governance.openapi.yaml` is canonical for the Control API. After changing it:

```bash theme={null}
cd apps/docs
npm run sync:contract
```

CI rejects a stale `openapi/next.yaml` snapshot.

After changing SQLx queries, run `scripts/prepare-sqlx.sh`; `scripts/check-sqlx-queries.sh` enforces that the offline metadata remains current. Exercise cross-service journeys with `tests/e2e/run.sh smoke` or `tests/e2e/run.sh full`.

See the repository's `CONTRIBUTING.md` for the issue-first workflow, Conventional Commit and PR naming, and CLA requirements.

## Publish a documentation version

Update the Cargo workspace and OpenAPI versions, finish the `Next` documentation, then run:

```bash theme={null}
cd apps/docs
npm run release:docs -- 0.1.0
```

The command refuses version mismatches and existing releases, freezes the MDX and API contract, and makes the new stable release the default Mintlify version. Do not edit a frozen release except to correct a material documentation or security error.

Commit the generated `apps/docs/<version>` directory, OpenAPI snapshot, and `docs.json` update before creating the release tag. The release workflow validates that the committed version is an exact snapshot of `Next` and stops before publishing binaries or images when it is missing or stale.

## Extend the product

Adding a harness requires a common harness variant, a single-writer configuration adapter, detection metadata, and gateway wiring. Adding a gateway requires a compiled `GatewayAdapter` plus any provider-specific proxy and credential lifecycle support; harness writers should not contain gateway-specific selection logic.

See [Harness adapter architecture](/next/development/harness-adapter-architecture) for the version-range contract, operation-set ownership, package compatibility, and required boundary tests.

See [Gateway adapter architecture](/next/development/gateway-adapter-architecture) for the compiled registry, service and harness ownership boundaries, provisioning choices, proxy changes, and end-to-end verification.