diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..04212c5
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,75 @@
+# Contributing
+
+Thanks for adding to the NullRun Python SDK. This file covers the
+mechanics of landing a change. For product context, see
+[README.md](./README.md) and the [docs](https://docs.nullrun.io).
+
+## Development setup
+
+```bash
+git clone https://github.com/nullrunio/nullrun-sdk-python
+cd nullrun-sdk-python
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+Python 3.10+ is required.
+
+## Tests
+
+```bash
+pytest -q                       # full suite
+pytest tests/test_v3_wire_contract.py::TestGateCache -q   # single file / class
+```
+
+Tests must pass before opening a PR. New public API requires tests —
+no exceptions. Source-pin regression tests live alongside the code
+they protect (see `tests/test_audit_p0_27_operation_id_hoist.py`
+for the canonical pattern).
+
+## Linting and types
+
+```bash
+ruff check src tests            # lint
+ruff format src tests           # auto-format
+mypy src/nullrun                # strict-ish type check
+```
+
+CI runs the same three steps plus pre-commit hooks (`trailing-whitespace`,
+`end-of-file-fixer`, `check-yaml`, `check-toml`). Do not bypass with
+`--no-verify`.
+
+## Commit hygiene
+
+We follow [Conventional Commits](https://www.conventionalcommits.org/).
+Common prefixes used in this repo:
+
+| Prefix     | Used for                                              |
+| ---------- | ----------------------------------------------------- |
+| `feat`     | New public API or behaviour                           |
+| `fix`      | Correctness fixes (cite the defect id)                |
+| `refactor` | Internal change with no observable behaviour shift    |
+| `docs`     | README / CHANGELOG / docstring-only changes           |
+| `test`     | New or rewritten tests                                |
+| `chore`    | Release prep, dep bumps, CI plumbing                  |
+
+Reference the defect id in the body when one exists
+(`DEF-OPID-REUSE-HASH-MISMATCH`, `NR-007`, …).
+
+## Pull requests
+
+- One logical change per PR. Drive-bys bundled into unrelated PRs get
+  rejected at review.
+- PR description: what changed, why, how to verify, any wire-shape or
+  ADR implications.
+- Wire-contract changes (anything that touches `_V3_ERROR_CODE_MAP`,
+  `transport.py`, the gate payload shape, or `runtime.check_workflow_budget`)
+  require an ADR reference. Coordinate before opening.
+
+## Issues
+
+- Use the GitHub issue templates.
+- Defects use the `DEF-*` prefix in the title. Probes / Q&A go to the
+  relevant `qa/` subtree in `nullrun-examples` — not this repo.
+- Security issues do **not** belong in public issues — see
+[SECURITY.md](https://github.com/nullrunio/.github/blob/main/SECURITY.md).
diff --git a/README.md b/README.md
index 6a12142..e58c521 100644
--- a/README.md
+++ b/README.md
@@ -37,7 +37,7 @@ LlamaIndex, and your own stack.
 
 ---
 
-> ⚠️ **Status: alpha (v0.16.4).** The public API may shift between minor versions.
+> ⚠️ **Status: alpha (v0.17.1).** The public API may shift between minor versions.
 > Pin your dependency and read the [CHANGELOG](https://github.com/nullrunio/nullrun-sdk-python/blob/master/CHANGELOG.md) before upgrading.
 
 ---
@@ -294,8 +294,9 @@ Runnable, copy-pastable examples live in a separate repo so you can adapt withou
 |---|---|---|
 | **v0.14.x** | ✅ alpha | Wire protocol v3.31, server-minted execution IDs, MCP, anti-OOM streaming cap |
 | **v0.15.x** | ✅ alpha | ADR-009 governance audit surface, typed `runtime.audit.*`, capability probes for `/audit-log/verify`, fail-OPEN observability closure |
-| **v0.16.x** (current) | ✅ alpha | Phase-1+ `action_digest` on `/gate`, `/execute` `tools` propagation, transient-5xx retry on gate (NR-006), error-code parity (NR-007, 41→56 entries) |
-| **v0.17** | 📋 planned | OpenTelemetry exporter, Redis-backed offline queue, hardened init contract |
+| **v0.16.x** | ✅ alpha | Phase-1+ `action_digest` on `/gate`, `/execute` `tools` propagation, transient-5xx retry on gate (NR-006), error-code parity (NR-007, 41→56 entries) |
+| **v0.17.x** (current) | ✅ alpha | Chain-setter Token discipline, `_GATE_CACHE` staleness closure, lazy-export repair, circuit-breaker lock unification (sync+async), op_id mint-fresh (DEF-OPID-REUSE-HASH-MISMATCH), error-code map closure (DEF-SDKT-004) |
+| **v0.18** | 📋 planned | OpenTelemetry exporter, Redis-backed offline queue, hardened init contract |
 | **v1.0** | 🎯 beta target | Stable wire contract, full async support, type-safe decisions |
 
 [Full roadmap & RFCs →](https://nullrun.io/roadmap)