# Contributing to Blackbox

First: thank you.

Blackbox is a primitive. The goal is to stay small, composable, and
impossible to ignore. Before contributing, read the philosophy below.

---

## Philosophy

**Add nothing that isn't strictly necessary.**

Blackbox should be the smallest possible thing that solves the problem.
Every feature we add is a feature someone has to understand, maintain, and trust.

When in doubt: don't add it.

**The spec is the contract.**

If a change breaks cross-language compatibility (a Python artifact
must always be verifiable by the TypeScript verifier and vice versa),
it's a breaking change and needs a major version bump.

**Zero production dependencies.**

The runtime (`@blackbox/runtime`, `aap-python`) must have zero
production dependencies. Stdlib only. This is non-negotiable.
Integration packages can have peer dependencies, never hard dependencies.

---

## What we welcome

- Bug fixes
- New framework integrations (new file in `packages/runtime/src/integrations/`)
- Python integration wrappers (new file in `aap/integrations.py`)
- CLI improvements (new commands, better output)
- Documentation improvements
- Test coverage

## What we don't want (yet)

- UI / dashboard
- Database backends
- Cloud sync
- Authentication
- Anything that requires a server to run

These might belong in a separate project built on top of Blackbox.
The primitive stays lean.

---

## Setup

```bash
# Python
python3 tests/run_tests.py   # should be ALL PASS

# TypeScript
cd packages/runtime
npm install
npm run build
node dist/index.js demo --fast
```

---

## Adding an integration

1. Create `packages/runtime/src/integrations/<framework>.ts`
2. Export from `packages/runtime/src/integrations/index.ts`
3. Add a usage example in the exports file
4. Add a Python counterpart in `aap/integrations.py` if applicable

Integrations must:
- Have zero required dependencies (peer deps only)
- Not modify agent behavior, only wrap it
- Handle errors gracefully (record the error, re-raise)
- Sanitize sensitive data before recording (no raw API keys, passwords)

---

## Tests

All core logic changes need tests in `tests/run_tests.py`.
Tests run with stdlib only — no pytest, no external deps.

```bash
python3 tests/run_tests.py
```

---

## Commit style

```
type: short description

types: fix | feat | docs | refactor | test | chore
```

Examples:
```
feat: add CrewAI integration
fix: handle empty output in file_write events
docs: add LangChain usage example to README
```

---

## Cross-language compatibility

If you change the event format or hashing logic, you MUST verify that:

1. An artifact generated by Python is verifiable by TypeScript
2. An artifact generated by TypeScript is verifiable by Python

The canonical JSON format (keys sorted alphabetically, no whitespace)
is the contract. Do not break it.

---

## Questions

Open an issue. We read them.
