Start here

Pick the path closest to what you are trying to do.

Users

Data steward / archivist

You want to diff dataset snapshots, understand what changed, and produce a usable changelog.

• Start with Diff two snapshots.
• If you need files you can keep or share, continue to Save and render changesets.
• If your dataset includes formats binoc does not understand yet, see Install and use plugins and Third-party plugins.
• If you want the framing before the mechanics, read Why binoc exists.

Pipeline integrator

You care about contracts, automation, and stable machine-readable output.

• Start with Changeset JSON schema.
• Read Dataset config for the YAML surface.
• Use Save and render changesets for output routing and Extract changed data for extracting the underlying changed records.
• Read Significance classification if you need to understand how semantic tags become user-facing severity.

Plugin developers

Python plugin author

You want to extend binoc with a comparator, transformer, or renderer in Python.

• Start with Plugin model.
• Then follow Write a Python comparator, Write a Python transformer, or Write a Python renderer.
• Keep Python API and Plugin discovery open while implementing.
• Before publishing, read Test a plugin with vectors and Publish a plugin.

Rust plugin author

You want the same extension points, but implemented in Rust.

• Start with Plugin model.
• Then follow Write a Rust comparator or Write a Rust transformer.
• Keep Rust SDK and Plugin discovery open while implementing.
• Before publishing, read Test a plugin with vectors and Publish a plugin.

Core developers

Core contributor

You are changing binoc itself rather than just using or extending it.

• Start with Contribute to binoc.
• Read Architecture overview next.
• Use Test vectors and Security and trust when touching those areas.
• Treat the ADR index as the long-form record of design decisions and rejected alternatives.

For contributor rules that live in the repository root rather than the docs site, see AGENTS.md.

Release manager

You are preparing a release rather than doing feature work.

• Start with Cut a release.
• Keep CLI, Python API, and Rust SDK nearby if you need to sanity-check a public surface.
• Use the ADR index when a packaging or compatibility question turns out to be a design question.