# 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 whe

Source: https://docs.tune.toys/contributors/contributing/

Start with [MVP scope](https://docs.tune.toys/contributors/mvp/), the [architecture overview](https://docs.tune.toys/contributors/architecture-overview/) and the README of the folder you intend to change. [AGENTS.md](https://github.com/joshstovall/TuneToys/blob/main/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`.

| Command                     | Required when                                                                                                            |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `npm run check`             | Any foundation code change; needs PostgreSQL 17 for `npm test` (see [database checks](https://github.com/joshstovall/TuneToys/blob/main/docs/delivery/database.md#checks)) |
| `npm run build:player`      | Native shell or Player changes, in addition to root checks                                                               |
| `npm run validate:examples` | Example or schema changes                                                                                                |

## 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](https://github.com/joshstovall/TuneToys/blob/main/docs/delivery/validation.md) lists current checks and gate suites.

## Decisions and review

- An architectural change records its reason, alternatives, consequences and compatibility impact in [docs/decisions](https://docs.tune.toys/contributors/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](https://github.com/joshstovall/TuneToys/blob/main/LICENSE.md) and [security boundaries](https://github.com/joshstovall/TuneToys/blob/main/SECURITY.md).