Docs: modelith.sh publishes from main, so it documents features no release has

[jbeda]

modelith.sh rebuilds from main on every push touching docs/** or website/** (see .github/workflows/deploy-docs.yml). So the site describes main, while brew install and the GitHub release give you the last tag. Those two have drifted, and it is visible to users today.

Latest release is v0.4.0 (2026-06-30). Against main:

$ git diff --stat v0.4.0 main -- docs/
 11 files changed, 776 insertions(+), 105 deletions(-)

The schema reference is the clearest case. Top-level properties in each:

v0.4.0: description entities enums glossary         invariants kind scenarios        title version
main:   description entities enums glossary imports invariants kind scenarios shared title version

https://modelith.sh/schema-reference documents imports and shared right now. Every object in the schema is additionalProperties: false. So you install v0.4.0, follow the published docs, write imports:, and get a structural lint error on a field the docs just told you to use. internal/lint/imports.go is not in v0.4.0 either, so a more forgiving schema would not have saved it.

This gets worse when the slice 2 work on #25 merges. modelith deps import and a full vendoring page publish to the site the moment it lands, and internal/deps is in no release at all. For anyone who installed from Homebrew, the command does not exist.

The schema URL has the same problem with sharper teeth

The plan is to serve the canonical schema at https://modelith.sh/schema/domain-model/v1.json so editors can fetch it from the # yaml-language-server: header. It is not live yet: that URL 404s, and there is nothing under website/static/.

If it gets served from main like everything else, the v1 an editor fetches and the v1 compiled into your installed binary can disagree. We decided to keep evolving v1 in place while pre-release rather than bumping to v2, so "v1" is not a stable contract yet. That failure is nastier than a wrong doc page: your editor says the file is valid, CI says it is not, and nothing on either side explains why.

Options

No favorite yet.

1. Docusaurus versioning. Snapshot docs/ per release, point lastVersion at the newest tag, publish main as "next" behind a dropdown. It is the built-in answer and it extends to the schema JSON. The cost is a full copy of docs/ per release living in the repo, which is real noise at this size.
2. Publish from tags instead of main. Change the deploy trigger and the site matches the binary exactly. The cost is that a typo fix does not go live until the next release, which stings when releases are weeks apart.
3. Banner only. Keep publishing main, add a site-wide note naming the current release and saying the docs describe unreleased code. Cheapest and honest. Does nothing for the schema URL, and does not help someone who lands on a deep link from a search engine.
4. Per-feature annotations, like "requires v0.5.0" on the sections that need it. Most work, and it rots silently the first time someone forgets one.

My instinct is (2) plus a preview build of main somewhere that is not the canonical domain, then (1) once there are users on more than one version. Happy to be argued out of that.

Open questions

• Should the schema JSON version independently of the docs? It already carries a version in its path. The answer changes depending on whether v1 keeps evolving in place after 1.0.
• showLastUpdateTime is already on. It tells you when a page changed, not which binary it describes, so I do not think it counts as a signal here. Worth confirming nobody is relying on it as one.