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 Plugin catalog.
• 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 changelog sections.

Plugin developers

Python plugin author

You want to extend binoc from Python.

• Start with Plugin model.
• Then follow Write a Python renderer for stable renderer work. Python rule authoring for the correspondence engine is deferred until the stable ABI tier lands.
• 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 correspondence rule packs or renderers implemented in Rust.

• Start with Plugin model.
• Then read Dispatch model and Write a Rust rule pack.
• 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.

Research

Background analysis and prior-art surveys that inform binoc's design without being normative documentation. This is where research notes are collected.

• Prior art and architecture precedents — which comparable tools exist (the build-vs-buy evidence) and which systems have the most to teach binoc's architecture.

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.