open-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/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.

## 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.