RFC: quickstart guide for framework development 2.0

[erikeah]

I ask for documentaion of how to setup framework development for mercur 2.0, that maybe could be translated to a DEVELOPMENT.md file in the repo.

This concern is because I'm facing difficulties while setting up the development environment, and I would like to know which steps I might follow to successfully start hacking and testing my own modifications from the monorepo.

[vholik]

Check the new latest release candidate developments guides and give us your feedback. https://docs.mercurjs.com/rc/resources/tutorials/first-marketplace

[erikeah]

@vholik Hi! I found the "consumer developer" documentation improved and pleasing, however what I'm asking for "framework development" documentation, quick start guide to start hacking mercurjs and contribute.

[vholik]

@erikeah For framework/contributor work the repo actually ships its development docs in-tree, under /docs:

• docs/ARCHITECTURE.md — the monorepo layout, how @mercurjs/core plugs into Medusa, packages vs. apps, request-flow examples.
• docs/PRODUCT.md — what the platform does, domain concepts (sellers, offers, commissions, payouts, order groups).
• docs/UI-ARCHITECTURE.md — the admin/vendor dashboard contract.

We drive development with an AI/spec-based flow: CLAUDE.md at the repo root is the entry point (build & run commands, project structure, working rules), and each feature is tracked as a spec under docs/specs/ (SPEC-001 … SPEC-024+) — one Markdown file per feature with its behavior, verification steps, and status. That's the source of truth for what's being worked on and how to verify it.

Quick start to hack on the monorepo:

bun install      # install deps (bun only — never npm/yarn/pnpm)
bun run build    # compile all packages
bun run dev      # API + admin (:7000) + vendor (:7001)
bun run test:integration:tests

Bug fixes/features go through those specs and must include tests; branches follow / and PRs target main.