Skip to main content
The one choice that shapes an install is topology — one repo or two. Whether the repo is brand new or already exists doesn’t change how you install; it only changes whether you seed the hub from scratch or populate it from code that’s already there.

Embed — one repo

Synclair lives inside the product repo, so its hub, skills, and guardrails travel with the code. Start a new project in the clone, or co-locate it into an existing repo.

Watch — two repos

Synclair is a separate repo beside the product, on its own server, documenting it one-way. The recommended way to adopt it onto existing code you’d rather not touch.
“New repo” vs. “existing repo” is not a separate install path — embed and watch each work on either. The only fork is one repo or two. See Setup modes for the trade-offs behind the choice.
The cleanest way to run any of this: point your AI agent at it and say “set me up with Synclair.” The project-bootstrap skill interviews you, clones the foundation, blanks the seed, and reseeds it to a working hub. The steps below are what it does under the hood.

​
Embed — one repo

Synclair and the product share a repo, so every agent working in it gets the hub, skills, and guardrails ambiently. You reach this topology two ways:
  • Starting fresh — the clone becomes your product repo; you build the app in it.
  • An existing repo — you co-locate Synclair at ./synclair, isolated so the two apps’ builds don’t collide.
1

Get the foundation into the repo

Starting fresh:
Existing repo: vendor Synclair at ./synclair (the co-locate-synclair skill does this and sets up the build isolation). Either way the foundation stays a git upstream remote so you can pull updates later.
2

Seed the hub

Starting fresh → reseed your brand: product name, color ramps, theme, optional domain skill. Onto existing code → run existing-project-intake so the hub populates from the real app — tokens, components, knowledge — instead of a blank seed.
3

Run the hub

Synclair runs on its own server at port 4100, mounted at /synclair — separate from the product’s app even in one repo:

​
Watch — two repos

Synclair runs as a separate sibling clone beside the product, on its own server, and lands nothing in the host repo. This is the recommended way to adopt Synclair onto an existing app you’d rather not disturb.
1

Clone Synclair as a sibling

The foundation stays a git upstream remote for pulling updates later.
2

Run it on its own port

Port 4100, browsed at localhost:4100/synclair. Your app keeps running wherever it already runs.
3

Populate from the host codebase

Run existing-project-intake against the product repo — its diggers survey the code, harvest the docs, extract the tokens, and catalog the components, so the hub reflects the real app instead of starting empty.
Watcher is one-way: Synclair observes and documents the host and lands nothing in its repo. The hub is at localhost:4100/synclair — never a route inside your app.

Next: which mode am I in, and what does it cost?

Embedded vs. watcher — the trade-offs, and how the choice shapes everything.