brainy/CONTRIBUTING.md

# Contributing to Brainy

Brainy is MIT-licensed and genuinely open to outside contributions. This page
is the honest, current path — please don't rely on older instructions you
may find elsewhere in the repo's history.

## Where the project lives

The source of truth is a self-hosted forge: **source.soulcraft.com/soulcraft/brainy**.
It's anonymously readable and cloneable — no account needed to browse, clone,
or build.

**github.com/soulcraftlabs/brainy** is a public read-only mirror. It's a fine
place to read code or star the project, but issues and pull requests opened
there won't be picked up — please use one of the paths below instead.

## How to contribute

**Found a bug, or have an idea?** Email **brainy@soulcraft.com**. No account,
no ceremony — you'll get a receipt, and it goes to a human.

**Want to send a patch?** Two ways, both first-class:

- **Email a patch.** Run `git format-patch` against your change and email the
  output to **brainy@soulcraft.com**. This is a genuinely supported path, not
  a fallback — plenty of good contributions arrive this way.
- **Open a pull request on the forge.** Request an account at
  **source.soulcraft.com** (registration is request-with-approval, so allow
  a little lag), clone, push a branch, and open a PR there. Maintainers
  review and land it.

Either way, for anything beyond a small fix, opening an issue first (email is
fine) to talk through the approach saves everyone rework.

## Development setup

```bash
git clone https://source.soulcraft.com/soulcraft/brainy.git
cd brainy
npm install
npm run build
npm test
```

Tests run on [Vitest](https://vitest.dev/). `npm test` runs the unit suite;
see `package.json` for `test:integration`, `test:coverage`, and friends.

## Standards

- **Strict TypeScript.** No `any` escape hatches to dodge the type checker.
- **Tests exercise real behavior.** No mocking away the thing you're supposed
  to be testing.
- **No stubs, no TODO-code.** If something can't be finished, say so and
  leave it out — don't merge a placeholder.
- **JSDoc on every exported function, class, and type.**
- **[Conventional Commits](https://www.conventionalcommits.org/).** `feat:`,
  `fix:`, `docs:`, `perf:`, `refactor:`, `test:`, `chore:`. Never
  `BREAKING CHANGE` in a commit message — major version bumps are a separate,
  deliberate decision.
- **Performance claims are measured or labeled projected.** If a PR or its
  description states a number, cite the benchmark that produced it (see
  [docs/performance-envelopes.md](docs/performance-envelopes.md) for the
  pattern). Don't state an estimate as if it were measured.

## License

Brainy is [MIT licensed](LICENSE). Contributions are accepted under the same
license — there's no CLA to sign.

Thank you for considering a contribution.