Skip to main content
In existing-project mode, Synclair catalogs the components your host app already has — props derived from the source, real usage snippets, live previews. That catalog is only useful while it matches the code. As the host app grows a new component or changes an existing one, the catalog has to keep up. There are two ways to keep it in sync. They’re not either/or — the CI is just the manual flow, automated.
This is a different axis from staying current with the foundation (pulling Synclair updates from upstream — that’s the synclair-sync skill, covered in Customizing). This page is about your host component catalog vs. your host code.

​
The two ways

Manual — run the cataloger

You (or an agent) run the cataloger skill on demand, and the drift checks tell you when something’s out of date. Full control, zero setup.

Automated — catalog-gate CI

A GitHub Actions workflow scans every PR, comments what catalog work it introduces, and — optionally — runs the cataloger on the branch for you. Nothing to remember.

​
Way 1 — run the cataloger yourself

Two skills do the cataloging; the checks tell you when to.
1

Catalog new or changed components

Point an agent at the component-cataloger skill (or existing-project-intake for a first full pass). It reads the host source, derives the props and tier, finds real usage, and writes the entry plus a live preview scene.
2

Check for drift on demand

Two commands, run from the Synclair app root, report where the catalog has fallen behind the code:
The hub surfaces the same signals visually on /synclair/components, so a stale or unrendered entry is visible without running anything.

​
Way 2 — the catalog-gate CI

The workflow (.github/workflows/synclair-catalog.yml) runs on every PR and has two halves:
A fast, dependency-free scan (scripts/ci-pr-catalog-check.mjs) looks only at what this PR changes and posts a sticky comment listing:
  • uncataloged component files the PR adds,
  • cataloged entries whose source the PR touches (they’d go stale on merge),
  • entries that are documented but not rendered.
It never nags about the pre-existing backlog, and it exits cleanly (posting nothing) in a repo with no host catalog yet — so it’s safe to ship dormant.
When there are gaps and you’ve added an ANTHROPIC_API_KEY repository secret, the workflow runs the cataloger agent on the PR branch and pushes a commit with the new entries and preview scenes — so the hub shows the components before the PR merges. Without the secret this half simply skips, and the gate comment still tells a human what to catalog.

​
Turning it on

1

Point the trigger at your host source

In synclair-catalog.yml, add your host component path(s) to paths: (e.g. - "src/**" or - "packages/ui/**") so host changes fire the gate. If Synclair is embedded at ./synclair, prefix the script and prompt paths with synclair/ (the script auto-detects the repo root — you only touch the YAML).
2

(Optional) add the API key to enable auto-cataloging

Add ANTHROPIC_API_KEY as a repository secret. Leave it off to keep the advisory-comment-only behavior.
Which should I use? Start with the gate comment — it’s free and answers “did this PR change the catalog?” on its own. Add the API key once you want the catalog to maintain itself. The manual cataloger is always there for a big first pass or a one-off.