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

# Sources

> Reference knowledge from other ByteRover projects with read-only cross-project search

## What Are Sources?

Sources let you reference curated knowledge from other ByteRover projects. When you add a source, its context tree becomes searchable alongside your own — without copying any data. Results are attributed to their origin so you always know where knowledge came from.

This is useful when:

* **Platform teams** share auth patterns, infrastructure conventions, or API guidelines
* **Shared libraries** document their conventions for downstream consumers
* **Design systems** provide component guidelines to frontend teams
* **Cross-team collaboration** requires visibility into each other's curated knowledge

## How It Works

Sources are **declarative, one-way references** stored in your project's `.brv/sources.json`. Nothing is written to the target project — it doesn't even know you've referenced it.

```
your-project/.brv/
  ├── config.json
  ├── context-tree/              # your local knowledge
  └── sources.json               # references to other projects
```

**`sources.json` structure:**

```json theme={null}
{
  "version": 1,
  "sources": [
    {
      "alias": "auth",
      "projectRoot": "/path/to/auth-service",
      "addedAt": "2026-04-10T12:00:00.000Z",
      "readOnly": true
    }
  ]
}
```

When you run a query, ByteRover searches:

1. Your local context tree first
2. Each configured source's context tree
3. Returns combined results with origin attribution

Local results get a slight relevance boost, so your own knowledge ranks first when equally relevant.

## Commands

All source commands are available as both CLI commands and TUI slash commands.

### `source add`

Add a read-only knowledge source from another ByteRover project.

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    brv source add <path> [--alias <name>]
    ```
  </Tab>

  <Tab title="TUI">
    ```
    /source add <path> [--alias <name>]
    ```
  </Tab>
</Tabs>

**Arguments:**

| Argument | Description                                               | Required |
| -------- | --------------------------------------------------------- | -------- |
| `path`   | Path to the target project (must have `.brv/config.json`) | Yes      |

**Flags:**

| Flag      | Description                                                             |
| --------- | ----------------------------------------------------------------------- |
| `--alias` | Custom identifier for the source. Defaults to the target directory name |

**Examples:**

```bash theme={null}
# Add a source with default alias (directory name)
brv source add /path/to/shared-lib
# Output: Added source "/path/to/shared-lib" as "shared-lib".

# Add with a custom alias
brv source add ../auth-service --alias auth
# Output: Added source "../auth-service" as "auth".
```

### `source list`

Display all configured sources and their validation status.

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    brv source list
    ```
  </Tab>

  <Tab title="TUI">
    ```
    /source list
    ```
  </Tab>
</Tabs>

**Example output:**

```
Knowledge Sources:
   shared-lib → /path/to/shared-lib (valid)
   auth → /path/to/auth-service (valid)
```

**With a broken source:**

```
Knowledge Sources:
   shared-lib → /path/to/shared-lib (valid)
   auth → /deleted/path [BROKEN - run brv source remove auth]
```

<Info>
  Broken sources (where the target's `.brv/` has been deleted) are excluded from search results but remain in the configuration until you explicitly remove them. This prevents silent data loss.
</Info>

### `source remove`

Remove a knowledge source reference. Only deletes the local reference — the target project is untouched.

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    brv source remove <alias-or-path>
    ```
  </Tab>

  <Tab title="TUI">
    ```
    /source remove <alias-or-path>
    ```
  </Tab>
</Tabs>

**Arguments:**

| Argument        | Description                                         | Required |
| --------------- | --------------------------------------------------- | -------- |
| `alias-or-path` | The source alias or full path to the target project | Yes      |

**Examples:**

```bash theme={null}
# Remove by alias
brv source remove auth
# Output: Removed source "auth" (/path/to/auth-service).

# Remove by path
brv source remove /path/to/shared-lib
# Output: Removed source "shared-lib" (/path/to/shared-lib).
```

## Search Integration

When you query a project with sources configured, results include origin information:

```bash theme={null}
brv query "JWT validation"

# Results might include:
# [local]:authentication/jwt-implementation/context.md     (your project)
# [auth]:security/token-validation/context.md              (from auth source)
```

### Origin Attribution

Each result is prefixed with its origin:

| Prefix    | Meaning                              |
| --------- | ------------------------------------ |
| `[local]` | From your project's context tree     |
| `[alias]` | From the named source's context tree |

### Relevance Ranking

* Local results get a slight score boost when relevance is similar
* Results from all sources are merged and ranked together
* The most relevant result wins regardless of origin

## Write Protection

Sources are **strictly read-only**. ByteRover enforces write guards at the tool level:

* Attempting to curate into a shared source fails with: `Cannot write to shared source — sources are read-only.`
* All mutation tools (`write_file`, `curate`) check file paths against source paths before allowing writes
* Protection is fail-closed: if context can't be determined, writes are blocked

This ensures you never accidentally modify another project's knowledge base through a source reference.

## Error Handling

| Error                             | Cause                                   | Resolution                                         |
| --------------------------------- | --------------------------------------- | -------------------------------------------------- |
| Target is not a ByteRover project | Path doesn't have `.brv/config.json`    | Initialize the target with `brv` first             |
| Cannot add self as source         | You tried to reference your own project | Add a different project                            |
| Duplicate source                  | Same path already configured            | The source is already available — no action needed |
| Circular source detected          | Target already references this project  | Remove one direction to break the cycle            |
| Source marked as BROKEN           | Target's `.brv/` was deleted or moved   | Run `brv source remove <alias>` to clean up        |

## Practical Examples

### Platform Team Sharing Auth Patterns

```bash theme={null}
# Auth team curates their patterns
cd /auth-service
brv curate "JWT tokens use RS256, expire in 24h, refresh tokens in 7d"

# Product team references auth knowledge
cd /product-api
brv source add /auth-service --alias auth

# Product devs can now query auth patterns from their own project
brv query "token expiration policy"
# Returns: [auth]:security/jwt-tokens/context.md
```

### Multi-Source Architecture

```bash theme={null}
cd /frontend-app
brv source add /design-system --alias design
brv source add /api-gateway --alias api
brv source add /shared-utils --alias utils

brv source list
# Knowledge Sources:
#    design → /design-system (valid)
#    api → /api-gateway (valid)
#    utils → /shared-utils (valid)

brv query "button component variants"
# Searches: local + design + api + utils context trees
```

### Combined with Worktrees

Sources configured in a parent project are automatically available from all linked worktrees:

```bash theme={null}
# Parent project configures sources
cd /monorepo
brv source add /design-system --alias design

# Worktree inherits sources through the pointer
cd /monorepo/packages/web
brv query "color tokens"
# Searches: monorepo context tree + design-system source
```