# 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/soulcraftlabs/open-brainy**.
It's anonymously readable and cloneable — no account needed to browse, clone,
or build.
## 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/soulcraftlabs/open-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.
## Test gate
The release gate is a bare `vitest run` (no `--config` flag) — the same
command the delta gate and CI's checks invoke. It carries the full
correctness suite and nothing else: wall-clock/scale benchmarks
(`tests/performance/**`, `tests/critical-performance-benchmark.test.ts`,
`tests/api/performance-benchmarks.test.ts`) and the two tests whose outcome
depends on the host machine or network rather than the code
(`tests/package-size-limit.test.ts` shells out to the `npm` CLI;
`tests/model-loading.test.ts` makes a real network call to download a model)
are excluded from it, because a timing threshold or a flaky network call has
no business failing a correctness check. That whole family runs on demand,
in its own exclusive slot, via `npm run test:perf`.
## 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.
- **Measurements carry numbers, not provenance.** Public commit messages and
docs give the SHAPE a number was taken at and never where it was taken: no
hostnames, no store or deployment identities, no operational anecdotes about
someone's running system. "A 14,056-noun / 72,679-verb production-shaped
store, measured solo under an exclusive lock" tells a reader everything the
number depends on; the machine it ran on and whose data it was tell them
nothing except where somebody's infrastructure lives.
- **Documents that answer or reference a confidential specification never enter
this repository, even summarized.** The public docs describe THIS engine and
the published contract, and nothing else — a summary of a private document is
still that document's contents.
## 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.
