restructure

docs/development.md

@@ -0,0 +1,93 @@
+# Development
+
+Run commands from the repository root. Rust stable and Python **3.11 or newer**
+are required. Lockfiles are committed for the core workspace, both CLAP wrappers,
+and the headless editor tool.
+
+## Product boundaries
+
+The catalog in [plugins/catalog.json](../plugins/catalog.json) defines product
+names, wrapper manifests, documentation, internal packages, and distribution
+licenses. Shared build/check/release tools consume it. Each wrapper's Cargo
+package version is the authoritative release version.
+
+The root workspace contains Rivet's core, MIDI, application, and offline preview
+crates, plus Patina's core, editor, and renderer. Wrappers under
+`plugins/<product>/plugin/` remain independent workspaces because they depend on
+a pinned NIH-plug Git revision. Their host identities and persistence stay separate.
+
+## Checks
+
+```sh
+cargo test --workspace --locked
+cargo clippy --workspace --all-targets --locked -- -D warnings
+python scripts/check-plugin.py --plugin rivet
+python scripts/check-plugin.py --plugin patina
+python -m unittest discover -s scripts/tests -v
+```
+
+The product check script checks formatting, tests, and lints that product's
+packages and wrapper without compiling the other plugin. Offline builds work
+once dependencies are cached; append `--offline` to manual Cargo commands.
+
+Native wrapper tests on Linux require pkg-config, X11/XCB, and OpenGL development
+headers. Rivet's optional standalone also needs ALSA/JACK headers. Gitea installs
+the headers needed by its check jobs.
+
+## Windows builds
+
+On Windows, install Rust and the MSVC build tools. For Linux cross-compilation,
+install the Rust `x86_64-pc-windows-gnu` target and MinGW's
+`x86_64-w64-mingw32-gcc`.
+
+```sh
+python scripts/build-plugin.py --plugin rivet --target x86_64-pc-windows-gnu
+python scripts/build-plugin.py --plugin patina --target x86_64-pc-windows-gnu
+python scripts/package-windows.py
+python scripts/package-windows.py --plugin rivet
+python scripts/package-windows.py --plugin patina
+```
+
+Build outputs use `dist/<target>/Rivet.clap` and `Patina.clap`, with docs and
+licenses retaining their directory structure. `CARGO_TARGET_DIR` is supported
+for sharing compilation between wrappers. MSVC packaging accepts
+`--target x86_64-pc-windows-msvc`.
+
+The combined ZIP is `dist/rivet-patina-windows-x86_64.zip`. Individual ZIPs use
+`<product>-windows-x86_64-<version>.zip`. Each ZIP has internal file checksums and
+an external `.zip.sha256`. ZIP metadata is deterministic; binaries still depend
+on the toolchain and build environment. Packaging includes only selected catalog
+entries, never old binaries left in `dist`.
+
+Linux builds remain available for local development; CI produces Windows release
+binaries only. Neither build nor packaging installs plugins into a DAW.
+
+## Editor previews
+
+```sh
+cargo run --manifest-path tools/editor-check/Cargo.toml -- /tmp/rivet.png --plugin rivet
+cargo run --manifest-path tools/editor-check/Cargo.toml -- /tmp/rivet-creative.png --plugin rivet --creative
+cargo run --manifest-path tools/editor-check/Cargo.toml -- /tmp/patina.png --plugin patina
+cargo run --manifest-path tools/editor-check/Cargo.toml -- /tmp/patina-compact.png --plugin patina --compact
+```
+
+Patina also accepts `--silent`, `--delta`, and `--bypass` as render fixtures.
+The tool compiles actual editor code and software-renders without a display.
+These checks do not establish native host embedding, keyboard routing, or audible
+artistic quality. Use the product guides for FL Studio acceptance checks.
+
+## Compatibility and naming
+
+| Product | Former display name | Preserved CLAP ID |
+| --- | --- | --- |
+| Rivet | Motif Storyboard | `io.storyboard.motif` |
+| Patina | Resonance Compressor | `io.storyboard.resonance-compressor` |
+
+Rivet retains `story-session-v1` and its session migration support; Patina retains
+all parameter IDs. No JSON/state migration is introduced by the rename. These
+historical identifiers and copyright notices intentionally remain in source.
+Replace old scanned plugin files before rescanning, rather than keeping duplicate
+CLAP IDs installed. Verify existing-project recall in FL Studio.
+
+See [release workflow](releases.md) for tagged publishing. Actual Gitea runner
+execution and FL Studio validation remain separate from local checks.