Contributing

Start with MVP scope, the architecture overview and the README of the folder you intend to change. AGENTS.md is the working agreement for humans and agents and takes precedence where it is stricter.

Local workflow#

1. Use the Node and npm versions pinned in the root manifest, install Rustup stable with the wasm32-unknown-unknown target, then npm ci --ignore-scripts and npm run check. npm and Cargo lockfiles freeze resolution. If your global npm cache is unavailable, use npm ci --ignore-scripts --cache /tmp/tunetoys-npm-cache; do not change ownership of unrelated local files.
2. For a schema change: bump its version if required, update examples and semantic validation, run npm run generate, and describe compatibility. Never edit generated types by hand.
3. npm run format formats source and docs. npm run docs:check requires a README in every source folder and verifies local Markdown links; both run inside npm run check.

Boundaries#

• Most folders are planned boundaries. Add a package manifest or build target only when there is real implementation and a meaningful check; documentation-only reservations need no dummy tests or no-op builds.
• Keep application-specific flows in apps/ and domain rules in shared packages/. Use @tunetoys/* for internal TypeScript packages; the workspace pattern already includes future packages under packages/, and services join workspace configuration with their first implementation.
• Avoid a service per domain: one modular API plus a separate worker process.
• Pure contracts may not import React, browser/OS APIs, databases or account services. Shared Frame code depends on a narrow runtime interface. Audio processing may not depend on editor state or cloud availability.
• Add dependencies at the owning package and update the lockfile. Never import runtime files from the sibling bit-audio checkout.

Testing#

Test at the behavioural boundary. Contract changes need malformed-input and compatibility cases; DSP changes need numeric, event and state fixtures on each admitted target. The validation matrix lists current checks and gate suites.

Decisions and review#

• An architectural change records its reason, alternatives, consequences and compatibility impact in docs/decisions. Label implemented behaviour, adopted direction and unproven proposals separately. A proposed performance budget is not a measured claim.
• Pull requests explain the concrete behaviour, the checks performed and remaining target limitations.
• Keep release changes reviewable: no build or check command may publish, install plugins, enable paid services or provision production resources as a side effect.
• Ports of legacy algorithms retain provenance and their original terms. Public licenses, publisher identity and release credentials need an explicit owner decision before distribution; see license status and security boundaries.