Core and projects
The core is the software. A project is your organisation’s setup on top of it. They are two repositories that never share a git history. You do not fork the core, and the core never holds your work.
Two kinds of repository
Section titled “Two kinds of repository”| The core | A project (one per organisation) | |
|---|---|---|
| Holds | the api, the web app, the docs, the runner, the CLI, templates, our own skills, the stack definition | pipelines/, transform/, semantic/, terms/, access/, perf/, secrets.yml, stack.yml, its own AGENTS.md additions |
| Changed by | pull requests to the core | your own pull requests |
| Released as | versioned images (ghcr.io/enum-studio/metrics-book-{api,jobs}:<version>), the metrics-book package, the docs at a versioned path |
your own deployment |
| Licence | Apache-2.0 | yours |
Nothing is published yet. The image names and the package are where the first release will put them.
Making a project
Section titled “Making a project”You make a project with the CLI:
mb init <name>mb init creates a repository with the project layout, a stack.yml, a generated compose.yml, an AGENTS.md for your agent, and a .metrics_book/ folder the CLI manages. Then mb templates install ecommerce starts you from the e-commerce template.
stack.yml pins the core version, for example core: 1.4.0. The generated compose.yml names the core’s images at that version. mb build builds your images from those plus your files, tagged with your commit, so every container of a deployment runs the same commit.
A project deploys like any compose application: a VM with Docker, Dokploy or Coolify.
Where you add your own
Section titled “Where you add your own”| To add | Where | How it reaches the stack |
|---|---|---|
| a source | pipelines/ (Python, dlt) |
the jobs image, scheduled in stack.yml |
| models | transform/ (dbt) |
the jobs image |
| metrics, dimensions, datasets | semantic/ (AML) |
anfra |
| reports and custom visualisations | semantic/apps/ |
the web app’s report host |
| terms | terms/ |
the catalog |
| who sees what | access/ |
Cerbos |
| your own jobs | jobs/ |
the runner, scheduled in stack.yml |
| an app outside the stack | anywhere | /api/v1 with a service account |
Changing the core itself means a pull request to the core. If you must change it before that lands, you can point stack.yml at your own build of the core images. That is the escape hatch, not the normal path.
The project format is a public interface
Section titled “The project format is a public interface”Everything the core reads from a project is the project format: the folder layout, stack.yml, secrets.yml, service_accounts.yml, assignments.yml, term frontmatter and the shape of a metric description. It has a version (format: 1 in stack.yml) and a JSON Schema per file. mb check validates every file against its schema.
Core versions follow semver. A change that an existing project would fail is a major version.
Upgrading without merging code
Section titled “Upgrading without merging code”mb upgrade <version>mb upgrade comes with the first release. It will show the changelog between your version and the new one, apply the format migrations the release ships, refresh .metrics_book/ and the generated files, and run mb check --all. You review the result as a normal pull request.
The project keeps what you own apart from what the CLI manages:
AGENTS.mdhas one block between<!-- metrics-book:begin -->and<!-- metrics-book:end -->. The CLI rewrites that block. The rest is yours.- Files under
.metrics_book/are never edited by hand. - Standards are on by default. You may turn off a named check in
stack.yml, for examplechecks: { off: [metric_name_prefixes] }.
See the CLI commands for the full list, and Contributing if you want to change the core.