The monorepo

glemour/
├── apps/
│   ├── storefront/   @glemor/storefront — Next.js, Vercel
│   ├── medusa/       @glemor/medusa     — Medusa v2, Railway   ← not a workspace
│   └── docs/         @glemor/docs       — this site
├── scripts/
│   ├── release.mjs      semver + both changelogs, no dependencies
│   └── gen-catalog.mjs  storefront catalogue → Medusa seed data
├── docs/             reference material that is not published
├── CONTRIBUTING.md   commit convention, the three gates, content honesty
└── DESIGN.md         the design system — authoritative for all UI work

Root package.json:

"workspaces": ["apps/storefront", "apps/docs"]

Why apps/medusa is not a workspace

Because hoisting breaks it.

npm workspaces lift shared dependencies into the root node_modules. Medusa v2 resolves its own modules — the framework, the CLI, the admin bundle, the migration runner — by walking the dependency tree it expects to find beside itself. Hoisted, that graph splits: two resolution roots, and medusa db:migrate fails.

So Medusa keeps its own node_modules and its own package-lock.json, and the root scripts reach it with --prefix rather than -w:

"medusa:dev":     "npm --prefix apps/medusa run dev",
"medusa:build":   "npm --prefix apps/medusa run build",
"medusa:migrate": "npm --prefix apps/medusa exec medusa db:migrate"

The install rule

Always npm install from the repo root for the two real workspaces. Installing inside apps/storefront or apps/docs creates a nested node_modules that silently shadows the hoisted one, and you then debug a version you are not running.

apps/medusa is the exception, and only because it is not a workspace: it installs in its own directory.

Scripts

Conventions

Commit format, the Release-Note: trailer, versioning and the content-honesty rules are in CONTRIBUTING.md. They are not repeated here; that file is the one that ships with the code.

UI work is governed by DESIGN.md. Its tokens beat your defaults, including on this site.