# Core concepts (/docs/concepts)

## Organization [#organization]

The organization is the root of everything in BarnDog. You connect to it once, when you sign in, and you never have to type it in a command again.

Inside the organization there are **teams**, **repositories** (each owned by one team), and **developers**.

## Origins [#origins]

Every asset has an **origin**, which is the scope that owns it. Commands take the origin with `--origin`:

| Origin             | Owner                                      |
| ------------------ | ------------------------------------------ |
| `org`              | The whole organization                     |
| `team/<team-slug>` | A team, such as `team/frontend`            |
| `repo/<repo-slug>` | A repository, such as `repo/dashboard`     |
| `dev/<handle>`     | A developer's personal assets              |
| `me`               | Shorthand for your own `dev/<your-handle>` |

Names are unique per asset kind within one origin. The same name can exist in different origins: `team/frontend` and `team/mobile` can each have their own `react-guidelines` Skill.

Behind the scenes, every asset has a permanent ID. Renaming an asset or moving it to another origin never breaks your selections or its history.

## Assets [#assets]

**Skills**, **MCP configurations**, and **Hooks** are the three kinds of asset.

- **Skills** are packages of files with a required `SKILL.md`. Each Skill has its own Git-backed history.
- **MCP configurations** describe how to connect to an MCP server. They list the secret variables a server needs, but credentials stay on your machine.
- **Hooks** run a command when a lifecycle event happens. Each Hook states which harnesses it supports, and BarnDog never claims it works where it doesn't.

## Recommended and optional [#recommended-and-optional]

Each scope marks its shared assets as **recommended** or **optional**. Recommended assets are the suggested setup. Optional assets are there for anyone who wants them. Neither kind is installed automatically: you always choose what to install.

## Your selections [#your-selections]

Your choices live in one file per machine, `~/.barndog/config.yaml`. They include:

- the harnesses BarnDog manages,
- the assets you installed, and whether each one is **enabled** or **disabled**.

Disabling an asset keeps it selected but removes it from your harnesses on the next sync. Enabling it again brings it back. Nothing you do locally changes the shared asset.

If two selections supply the same asset, it is installed once. If two different assets would end up with the same name in one harness, BarnDog stops and asks you to resolve it instead of picking one silently.

## Published, Draft, and Suggested Change [#published-draft-and-suggested-change]

Shared Skills and Hooks move through three states:

- **Published**: the current version everyone receives through `barndog sync`. Published versions are numbered `v1`, `v2`, and so on, and never change once published.
- **Draft**: private, unfinished edits in the web workspace.
- **Suggested Change**: a proposed edit waiting for review, like a pull request. When it is merged, it becomes the next published version.

Members merge Suggested Changes under their team's or repository's merge rules. Admins can publish directly. See [Review and merge Suggested Changes](/docs/guides/review-changes).