Skip to main content
Documentation that depends on discipline rots. A convention a team agrees to is a convention someone stops following at 5pm on a Thursday — and an agent moving fast will find the gap before you do. So none of Synclair’s rules are left to discipline. npm run verify-ui has to pass before any UI work counts as done, and CI runs the same gate on every pull request.
Look at what the list below is mostly made of. Not “did you write the docs” — but “is this claim still true.” A catalog that confidently describes something that has since moved is worse than no catalog at all, because people act on it.

​
What each check refuses

​
The design system holds

​
The catalog isn’t lying

Three directions a catalog can be wrong, and each has its own sweep:

Inaccuracy

check:coverage — does the catalog match what exists?

Redundancy

check:tiering — are three entries secretly the same thing?

Absence

check:recipes — is a pattern used everywhere that nothing documents?
Absence is the one most catalogs never check. A component library can be perfectly accurate about every entry it contains and still be useless, because the thing everyone actually copy-pastes was never added.

​
Nothing has gone stale underneath you

Freshness resolves to fresh, stale, or unanchored — and that third state matters. A host repo that isn’t checked out on this machine can’t be judged, so the hub shows nothing rather than crying wolf. Data written before the freshness contract existed resolves to unanchored too, never to a false stale.

​
The foundation stays portable

That last one is the subtlest failure Synclair has shipped a check for, and it’s worth understanding. The server had a probe (does it run?) and a contract check (do its tools return real content?). Both pass while every agent in the repo still reads whole files by hand — because neither asks whether the thing is registered.The gap is silent by construction. Telling agents “not offering those tools? register once” asks an agent to notice an absence, which is the one thing it reliably cannot do: nothing surfaces a tool that was never offered. It just reads files instead, all session, at many times the tokens the tools would have cost. So the generated status block in AGENTS.md now states whether the server is registered rather than advising agents to prefer it.

​
The checkers check themselves

This is the part worth stealing even if you never use Synclair: the seams whose failure mode is a plausible wrong answer get self-tests, not just the seams that can crash. A crash tells you something is broken. A confidently wrong catalog doesn’t.

​
When a check fails

The error messages name the fix. Two rules:
  • Don’t eslint-disable around a guardrail. If the token rule is genuinely wrong for a case, the token vocabulary is what needs changing — that’s a design decision, and it belongs in lib/system/tokens.ts where everyone inherits it.
  • Don’t hand-edit a generated digest to make a freshness check pass. Re-run the generator (the pages-map, codebase-map, or ux-doc skill). Editing the artifact makes the check green and the claim false, which is the exact failure the check exists to catch.

Related: day to day

Where these fit in the normal loop of building something.