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

# Overview

> Share curated knowledge across monorepos, git worktrees, and independent projects

## The Problem

Real-world projects rarely live in a single directory. Monorepos contain multiple packages. Git worktrees create parallel checkouts. Related services live in separate repositories. Without multi-project support, each directory gets its own `.brv/` context tree — forcing teams to curate the same knowledge multiple times.

ByteRover solves this with two complementary features:

| Feature                                  | Purpose                                 | Relationship                         |
| ---------------------------------------- | --------------------------------------- | ------------------------------------ |
| [Worktree](/knowledge-sharing/worktrees) | Link subdirectories to a parent project | One knowledge base, many directories |
| [Source](/knowledge-sharing/sources)     | Reference knowledge from other projects | Read-only cross-project search       |

## When to Use Each

### Worktrees — Same Project, Multiple Directories

Use worktrees when directories belong to the **same logical project** and should share a single context tree. Common scenarios:

* **Monorepo packages** — `packages/api/`, `packages/web/`, `packages/shared/` all share the monorepo's curated knowledge
* **Git worktrees** — Parallel checkouts of the same repo for concurrent work
* **Sibling checkouts** — Multiple clones of the same project

```bash theme={null}
cd /monorepo
brv worktree add packages/api
brv worktree add packages/web
```

After setup, running `brv query` from `packages/api/` searches the monorepo's context tree — no duplication needed.

### Sources — Different Projects, Shared Knowledge

Use sources when you want to **reference knowledge from another project** without copying it. Common scenarios:

* **Platform team patterns** — Your product repo references the auth service's curated patterns
* **Shared libraries** — Multiple consumers reference the library's documented conventions
* **Design systems** — Frontend repos reference the design system's component guidelines

```bash theme={null}
cd /product-repo
brv source add /path/to/auth-service --alias auth
brv source add /path/to/design-system --alias design
```

After setup, `brv query "JWT validation"` searches your local context tree **plus** both sources, with results attributed to their origin.

## How They Work Together

The real power emerges when combining both features:

```
monorepo/                             # main brv project
  .brv/
    ├── context-tree/                 # curated once
    ├── sources.json                  # references design-system
    └── worktrees/
        ├── packages-api/link.json
        └── packages-web/link.json
  packages/api/
    .brv                              # pointer file -> monorepo
  packages/web/
    .brv                              # pointer file -> monorepo

design-system/                        # separate project
  .brv/
    └── context-tree/                 # component patterns
```

From `packages/api/`:

1. ByteRover follows the `.brv` pointer to the monorepo
2. Searches the monorepo's context tree (local knowledge)
3. Searches the design system's context tree (shared source)
4. Returns results with origin attribution: `[design]:components/button.md`

## Key Design Principles

* **No duplication** — Worktrees point to the parent's context tree; sources reference in-place. Nothing is copied.
* **Git-style mental model** — Worktree pointers use the same `.brv` file/directory duality that Git uses for `.git` in worktrees.
* **Read-only sources** — Sources are never modified through the referencing project. Write guards prevent accidental mutations.
* **Origin attribution** — Query results always show where knowledge came from, so you know the source.
* **No sync required** — Both features are declarative references, not sync mechanisms. Changes in the target are immediately visible.

## Next Steps

<CardGroup cols={2}>
  <Card title="Worktrees" icon="folder-symlink" href="/knowledge-sharing/worktrees">
    Link directories to share a single context tree across your workspace
  </Card>

  <Card title="Sources" icon="book-open" href="/knowledge-sharing/sources">
    Reference knowledge from other projects with read-only cross-project search
  </Card>
</CardGroup>