Update rules
The docs stay correct only if they change together with what they describe. These rules apply to everyone: maintainers, outside contributors and AI assistants working in the repository. The same rules are written for Claude in apps/docs/CLAUDE.md, and the pull request template links here.
What triggers a docs change
| Change | Docs work, in the same pull request |
|---|---|
| Spec change (new field, enum value, rule, version, deprecation) | Edit the spec file in spec/ first, then the guides and examples that depend on it. |
| Public API change in a package | The TSDoc in the source (the API reference follows) and every guide that uses the API. |
| Behavior change with no API change | The guide that describes the behavior. |
| Release | Nothing by hand. Changelogs come from changesets. |
| Internal refactor | Nothing. |
| English page edited | Nothing in Portuguese. The CI warning lists stale PT pages; the on-page "behind" notice comes with the PT release. |
When to edit each spec file, and what to update in it, is described in packages/core/CLAUDE.md ("Documentation requirements") and spec/README.md. Spec files stay plain GitHub-readable Markdown: no site components or syntax.
Checks in CI
The docs — Check workflow runs on pull requests that touch apps/docs/, spec/, packages/ or .changeset/.
| Check | Command | Effect |
|---|---|---|
Every .well snippet and example in the docs validates with @welldot/core | pnpm --filter docs check:examples | Blocking |
| Internal links and anchors resolve, including links into spec headings | pnpm --filter docs check:links | Blocking |
| The docs site builds | pnpm --filter docs generate | Blocking |
The core tests that compare the spec with the code (vocab.test.ts, examples.test.ts) | pnpm --filter @welldot/core test | Blocking (CI runs it) |
A changeset for a published package with no change under apps/docs/ or spec/ | pnpm --filter docs check:touched | Warning only |
| Portuguese pages behind their English page (once they exist) | pnpm --filter docs check:translations | Warning only |
A renamed spec heading therefore fails the build instead of silently breaking the guides that link to it. Many changes need no docs, which is why the changeset check only warns.
End-of-change checklist
Run through this at the end of any change that touches the spec or a published package:
Did a rule change?
Edit the spec file first, as plain Markdown.
Which docs pages explain or depend on the change?
Update them, linking to the spec instead of restating it. Search apps/docs/content for the field, function or rule name.
Do the examples still validate?
Run pnpm --filter docs check:examples, and the @welldot/core tests if examples in packages/core/examples changed.
Did an English page change?
Its Portuguese page, when there is one, shows up in the CI warning for stale translations. Nothing else is needed unless you are asked to translate.
Is there a changeset?
Add one for every published package you changed (pnpm changeset). The changelog page follows from it.
In the pull request
The pull request template has three boxes for this:
- Spec updated first, if a rule changed
- Docs pages that depend on the change updated (or none needed)
- Examples validate (
check:examples) and links resolve (check:links)