docs: add CONTRIBUTING.md

CONTRIBUTING.md

@@ -0,0 +1,92 @@
+# Contributing to Stealth
+
+Contributions are welcome. This document explains how to set up the project, submit changes, and what we expect during code review.
+
+## Before you start
+
+- **Open an issue first** for non-trivial changes so we can discuss the approach before you invest time writing code.
+- **Keep PRs focused** — one concern per pull request.
+- **Stay aligned with the project's philosophy** — Stealth is a local-first, privacy-preserving analysis engine. Changes that introduce external service dependencies or move away from this model are generally not a good fit.
+
+See [GOVERNANCE.md](GOVERNANCE.md) for how decisions are made.
+
+## Setup
+
+### Requirements
+
+- [Rust](https://rustup.rs/) (stable, >= 1.93.1)
+- [Bitcoin Core](https://bitcoincore.org/) (>= 29.0) — needed for integration tests
+
+### Building
+
+```bash
+cargo build --workspace
+```
+
+### Running tests
+
+```bash
+cargo test --workspace
+```
+
+Integration tests start a local `bitcoind` in regtest mode automatically via `corepc-node`.
+
+### Code formatting and linting
+
+CI enforces both. Run these before pushing:
+
+```bash
+cargo fmt --all
+cargo clippy --workspace --all-targets -- -D warnings
+```
+
+Formatting rules are defined in `rustfmt.toml` (100-char line width, 4-space indentation).
+
+## Submitting a pull request
+
+1. Fork the repository and create a branch from `main`.
+2. Write your code, add tests if applicable.
+3. Make sure `cargo fmt`, `cargo clippy`, and `cargo test` pass.
+4. Open a pull request against `main`.
+
+### Commit messages
+
+Use [conventional commits](https://www.conventionalcommits.org/) format:
+
+```
+feat(engine): add peeling chain detector
+fix(bitcoincore): handle missing address in listunspent
+refactor(model): extract WalletHistory builder
+test(engine): add CIOH edge case
+docs: update README with CLI usage
+```
+
+### During review
+
+Once your PR is open and under review:
+
+- **Do not rebase or force-push.** If you need to make changes, add new commits. Force-pushing destroys the review context — reviewers lose track of what changed between rounds and have to start over.
+- **Do not squash commits during review.** Keep fixup commits separate so reviewers can see exactly what changed in response to each comment.
+
+This follows the same approach used by [Envoy](https://github.com/envoyproxy/envoy/blob/main/CONTRIBUTING.md), [LLVM](https://llvm.org/docs/GitHub.html), and [Miri](https://github.com/rust-lang/miri/blob/master/CONTRIBUTING.md).
+
+## Project structure
+
+```
+stealth/
+  model/          # Shared types, traits, configuration (stealth-model)
+  engine/         # Detection engine, heuristics, TxGraph (stealth-engine)
+  bitcoincore/    # Bitcoin Core RPC gateway (stealth-bitcoincore)
+```
+
+## What we look for in code
+
+- Use `bitcoin` crate types (`Txid`, `Address`, `Amount`) instead of raw strings and floats.
+- Prefer borrowing (`&`) over `.clone()` when you only need to read.
+- Prefer generics over `dyn` trait objects when the concrete type is known at compile time.
+- Keep thresholds and constants configurable via `DetectorThresholds`, not hardcoded.
+- All detectors should be covered by integration tests.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).