# Update rules

> Which code and spec changes need a docs change in the same pull request, what CI checks automatically, and the checklist to run at the end of every change to the spec or a published package.

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`](https://github.com/welldothq/welldot/blob/main/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`](https://github.com/welldothq/welldot/blob/main/packages/core/CLAUDE.md) ("Documentation requirements") and [`spec/README.md`](https://github.com/welldothq/welldot/blob/main/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:

::steps

### 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`)