Contributing

Thanks for your interest in BRAIN.

Setup

Follow docs/SETUP.md to get the app running against the bundled sample vault.

The auth and security tests are non-negotiable — never disable or skip them.

# api
cd api && uv run pytest

# web
cd web && npm test

# api
cd api && uv run ruff check . && uv run ruff format --check .

# web
cd web && npm run lint

Branch off main. One feature or fix per PR.
Conventional Commits (feat:, fix:, refactor:, docs:, …) are encouraged but not enforced.
Keep changes scoped: don't refactor adjacent code unless it's necessary for the change.

Before requesting review, confirm:

Tests pass locally.
Lint passes locally.
You did not weaken any of the security invariants documented in docs/security.md. In particular: every protected route still goes through verify_internal_jwt; the GitHub signIn callback still rejects non-allowed users; /admin/reindex still requires X-Admin-Token and not a user JWT; the api still has no published host port.
If you touched routing or auth, you ran the relevant sections of docs/pen-test-checklist.md.
No real secrets, vault content, or personal info in the diff.

Use GitHub Security Advisories on this repository — see SECURITY.md. Do not open a public issue.