# Contributing

Thanks for helping improve LLM Gateway.

The project values changes that make AI routing safer, easier to understand, easier to run,
and easier to verify.

## Contribution Areas

Good first contribution areas:

- documentation improvements
- bridge health checks
- provider adapters
- tests for subscription discovery
- dashboard clarity
- metrics and observability
- local-first routing policies
- security hardening

Larger contribution areas:

- new subscription bridge implementations
- policy engine improvements
- context receipt support
- reproducible run records
- MCP tool support
- database-backed audit trails

## Ground Rules

- Do not commit credentials, OAuth files, cookies, private keys, database dumps, training data,
  logs with account data, private hostnames, or local machine paths.
- Prefer explicit configuration through environment variables.
- Keep default behavior local and safe.
- Make operational state honest. Use `unknown`, `config_needed`, or `degraded` when the gateway
  lacks evidence.
- Add tests when changing routing, bridge behavior, authentication, or request validation.
- Keep public examples generic.

## Development Setup

```bash
npm install
npm run dev
```

Build:

```bash
npm run build
```

Test:

```bash
npm test
```

Secret scan:

```bash
gitleaks dir . --redact
```

## Branch And Commit Style

Use a short branch name:

```text
feature/subscription-health
fix/bridge-timeout
docs/quickstart
```

Use concise commit messages:

```text
docs: add subscription bridge guide
fix(gateway): handle bridge timeout
test(subscriptions): cover join flow
```

## Pull Request Checklist

Before opening a pull request, confirm:

- the change has a clear purpose
- public docs do not contain private infrastructure details
- build or tests were run
- bridge or API changes have a smoke test
- no credentials or account artifacts are included
- the pull request explains risk and rollback if relevant

## Adding A Provider

Provider changes should include:

- a descriptor or provider config entry
- health behavior
- model IDs
- expected auth state
- local test notes
- error handling for missing CLI or unreachable bridge

## Adding Documentation

Documentation should be direct, testable, and operator-friendly.

Prefer:

- commands that can be copied
- exact endpoint names
- clear expected results
- explicit security notes

Avoid:

- private URLs
- screenshots with account data
- local usernames or paths
- long fake credentials
- claims that are not supported by code

## Maintainer Review

The maintainer may ask for:

- smaller pull requests
- additional tests
- simpler defaults
- stronger security posture
- clearer docs
- removal of private data

That review is part of keeping the gateway usable and publishable.