Skip to main content
Synclair is always a foundation for a product. The one structural question is where the clone sits relative to that product — inside its repo, or beside it. That single fact drives how updates flow, whether agents get Synclair’s skills ambiently, and how the hub frames what it documents. There are exactly two modes, named for topology.

​
The two modes

​
Why named by topology, not by “sync”

It’s tempting to name the modes after which way they sync — but two different syncs pull in opposite directions, so “the sync mode” is ambiguous:
  • Code ↔ knowledge tightness favors embedded — one repo means skills, digests, and the catalog live with the code and version with it.
  • Foundation-update ease favors watcher — a separate clone pulls upstream Synclair updates as an ordinary merge, with no risk of entangling the product repo’s history or tooling.
Because the two tugs point at different modes, topology is the one unambiguous axis: a clone is either inside the product repo or beside it. The sync trade-offs are a consequence of that choice, not the label.

​
Pros and cons

​
Embedded

Pros
  • Ambient guidance — skills and knowledge are bridged to the repo root, so any agent building in the product (Claude Code, Cursor, Copilot, Codex) gets the guardrails and context automatically, without knowing Synclair exists.
  • One clone, whole team — whoever clones the product repo has the hub, the skills, and the knowledge. Nothing extra to distribute or keep running.
  • Knowledge versions with the code — a catalog or digest update rides the same PR as the code change it describes, so hub-vs-code drift is structurally harder.
  • CI can hold the line — the catalog gate comments on the product’s own PRs, and verify-ui runs beside the product’s checks.
Cons
  • Foundation updates are heavier — pulling upstream Synclair improvements means a subtree-style merge into the product repo’s history, not a clean, isolated pull.
  • Isolation is on you — the product’s build/lint/typecheck/deploy must be walled off from Synclair’s so neither trips over the other. The co-locate-synclair skill does this, but it’s real setup and a standing surface to maintain.
  • A footprint in the repo — an extra app, its dependencies, and its history now live in the product repo, and the team has to be okay with that.

​
Watcher

Pros
  • Zero footprint on the product — nothing lands in the host repo. You can adopt it on a codebase you don’t own, can’t commit to, or aren’t ready to change — and discard it just as freely.
  • Clean foundation updates — upstream Synclair improvements arrive as an ordinary git merge in the clone’s own repo, with no risk to the product’s history or tooling.
  • A stakeholder view without touching the product — the hub documents the app for designers, PMs, and leadership with no change to the product’s CI or deploys.
Cons
  • No ambient skills in the product repo — agents working in the host don’t get Synclair’s guidance automatically; the know-how sits in the clone next door.
  • Sync is a check, not a guarantee — the catalog describes code in another repo, so staying current is a drift check (check:host, the catalog-gate CI) rather than something the same PR enforces.
  • One more thing to distribute — teammates need the companion clone (or a hosted hub) to see any of it.

​
Which should I pick?

Pick embedded when…

You’re starting a new project, or you want agents building in your repo to get Synclair’s skills and knowledge ambiently, and one-repo ergonomics matter more than frictionless foundation updates.

Pick watcher when…

You’re adopting Synclair onto an existing app you’d rather not touch, and you want foundation updates to stay a clean, isolated merge. This is the recommended default for existing code.
Whichever you pick, ask the topology question deliberately at intake — don’t let it fall out of which install doc you happened to open. New-vs-existing decides how the hub gets seeded, not where the clone sits.

​
”Standalone” is not a third mode

A brand-new project that clones Synclair and builds the product in the clone is already embedded — the product and Synclair share one repo from commit one. “Standalone” is just embedded before the product files have been added. That pre-product state is a blank / unresolved marker, not a mode of its own.

​
How the clone remembers its mode

The mode is recorded once, explicitly, so every agent and every page reads the same answer instead of re-guessing. It lives in a small file (data/setup.json), resolved determine → confirm → record: install paths write it authoritatively; otherwise Synclair infers it from repo topology, confirms with you, then records it. The hub chrome shows a small “Embedded mode” / “Watcher mode” badge so you always know which you’re in. (The upstream foundation repo itself ships blank — it’s never “set up”.)

Next: tour the hub

What each section of the Synclair hub is for.