Contributions that improve qi's JSON synchronization, durable embedding boundary, libp2p integration, tests, and documentation are welcome. Before proposing a larger feature or public API or protocol change, open an issue to discuss its scope. qi is experimental and pre-1.0, but changes should remain focused and preserve existing behavior unless a change is explicitly agreed upon.
Use the Go version declared in go.mod. Before proposing a change, run the full validation suite from the repository root; the authoritative command list lives in AGENTS.md. Use gofmt -w on the same files it lists to fix any formatting that the check reports.
Add or update tests for behavior changes. Keep examples executable and update the owning documentation surface when user-visible behavior changes. For CLI synchronization changes, also follow the clean two-peer procedure in docs/usage-guide.md.
qi owns document generations, durable checkpoint acceptance, peer cursors, synchronization framing, document routing, and the libp2p integration. Keep CRDT primitives and transport-agnostic causal behavior in yin. Keep application-specific board, chat, membership, discovery, and authorization policy in embedding applications unless repeated integrations demonstrate a general qi boundary.
Preserve the distinction between visible JSON projections, complete qi checkpoints, embedded yin snapshots, and yin deltas. Generation checks must happen before yin ingest, and causal replica IDs must remain distinct from document and transport identities.
README.mdis the user-facing project entry point.docs/usage-guide.mdexplains CLI operation and recovery.docs/generation-checkpoints.mddefines durable mutation and generation behavior.AGENTS.mdrecords repository guidance for contributors and coding agents.- Go comments document exported API contracts and trust boundaries.
Link to the authoritative surface instead of duplicating detailed procedures.
Maintainers publishing a version should follow the release procedure.