Contributing to Mozaiks¶

Mozaiks is open source under the MIT license. This section is for people working on the framework itself — changing runtime code, adding factory workflows, improving Studio, or maintaining the release pipeline.

If you are building an app with Mozaiks, you do not need this section. Start with Getting Started instead.

Your First Pull Request¶

The full mechanical path — fork, branch, install development dependencies, make a focused change, run the relevant tests, and open a pull request — plus what you can contribute without MongoDB, Node.js, a running Studio instance, or an LLM API key (documentation, most Python tests, and many CLI changes) is documented once, in CONTRIBUTING.md. Start there.

Where to start¶

• Local Setup — source checkout, editable install, and how to run the builder stack from repo
• Architecture — how the runtime, app bundle contract, module system, workflows, and frontend fit together
• AI Policy — what we ask of AI-assisted contributions, and the repository-boundary mistake coding agents make most often here
• Agent Bootstrap Prompt — hand a task to Claude Code, Cursor, or Copilot with the repo-aware bootstrap prompt
• Contributor Guidance Readiness — current skill coverage, routing map, deferrals, and guidance validation tests

Getting Help¶

Ask in Discord — questions about an approach are welcome before you write the code, and usually save everyone a review cycle.

Preview the Docs Locally¶

Install the docs dependencies:

pip install -e ".[docs]"

Start the live-preview server from the repo root:

python -m mkdocs serve

Open http://127.0.0.1:8000 — the site rebuilds automatically when you save a file.

Release and Maintenance¶

• Releasing — release hold and future publish workflow
• Verified Setup Guide — maintainer-verified local environment
• Auth Setup — Keycloak and auth configuration
• Trigger Mechanisms — workflow trigger reference

Repo Structure¶

The canonical repo layout is documented in ARCHITECTURE.md.

Key boundaries:

Design Principles¶

• Structured-output-first — every canonical YAML contract must be representable as a strict typed model
• Declarative-first runtime — no hardcoded workflow behavior in the runtime
• No obsolete shims — this repo is pre-production; replace outdated logic cleanly
• Pre-production cleanup policy — optimize for the cleanest canonical implementation, not stale-behavior preservation