> ## Documentation Index
> Fetch the complete documentation index at: https://docs.synclair.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Two ways to install, by topology: embed Synclair in the product repo, or watch it from a separate one. Either works whether the repo is new or already exists.

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.

<CardGroup cols={2}>
  <Card title="Embed — one repo" icon="code-merge">
    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.
  </Card>

  <Card title="Watch — two repos" icon="eye">
    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.
  </Card>
</CardGroup>

<Note>
  "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](/setup-modes)
  for the trade-offs behind the choice.
</Note>

<Note>
  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.
</Note>

## 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.

<Steps>
  <Step title="Get the foundation into the repo">
    Starting fresh:

    ```bash theme={null}
    npx synclair new my-product   # clones the foundation into ./my-product
    ```

    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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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:

    ```bash theme={null}
    npm install && npm run dev   # http://localhost:4100/synclair
    ```
  </Step>
</Steps>

## 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.

<Steps>
  <Step title="Clone Synclair as a sibling">
    ```bash theme={null}
    #   my-app/            ← the product, untouched
    #   my-app-synclair/   ← the Synclair companion clone
    ```

    The foundation stays a git `upstream` remote for pulling updates later.
  </Step>

  <Step title="Run it on its own port">
    Port **4100**, browsed at `localhost:4100/synclair`. Your app keeps running wherever
    it already runs.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Warning>
  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.
</Warning>

<Card title="Next: which mode am I in, and what does it cost?" icon="diagram-project" href="/setup-modes">
  Embedded vs. watcher — the trade-offs, and how the choice shapes everything.
</Card>