Contributor Guide

Core boundaries and architectural conventions every contribution must respect.

Core Rules

Rule	Detail
No global registries	Pass dependencies locally and explicitly in core pipelines; ServiceRegistry is GUI-composition only, covering NiceGUI composition and ViewModels, while CLI and review runtimes construct their services directly
No bundled frontend	Use the separate GUI components (e.g. NiceGUI); never embed a heavy compiled web frontend
Rotation assets are gated	The user/ and tunes/ directories are absent, so rotation and afro pipeline work is asset-gated and nonportable
Review server needs a real dist dir	review_server.py requires a valid existing --dist-dir; the default path points outside the repository structure

Workflow

1. Use the uv workspace structure defined in the root pyproject.toml.
2. Respect package boundaries — core audio in audio_core, DJ logic in mixbox, valaro standalone.
3. Add configuration changes through the Pydantic models in mixbox.config.models.
4. Mark pipeline tests with the appropriate pytest markers (e.g. integration, slow).

Documentation

Policy	Rule
Location	New documentation belongs in the Quartz knowledge base under q5vault/
Filenames	Lowercase kebab-case
Cross-links	Relative Quartz wikilinks
Source grounding	Listed in the page’s frontmatter sources: key — never as body citations