# Cross-Vault Federation

Federation enables cross-namespace URI resolution — referencing documents in other vaults.

## Federation modes

| Mode | Behavior |
|------|----------|
| `none` (default) | All URIs resolve locally. Cross-namespace references are rejected. |
| `federated` | URIs with a namespace authority are resolved via the registry. Both nests must be enrolled. |
| `scoped` | Like `federated`, but the target namespace must appear in an explicit allow-list. |

## Configuration

Set the federation mode in `.context/config.yaml`:

```yaml
name: "My Project"
namespace: "my-project"
federation: none
```

## Cross-namespace URIs

```
contextnest://platform/infra/networking
             ^^^^^^^^
             namespace (authority)
```

A URI **without** an authority component always resolves within the current namespace:

```
contextnest://nodes/architecture
→ resolves locally, regardless of federation mode
```

## Scoped federation

In `scoped` mode, configure the allow-list in `config.yaml`:

```yaml
federation: scoped
federation_allow:
  - platform
  - shared-knowledge
```

Namespaces not on the allow-list are treated as unreachable.

## Design rationale

The default is `none` for safety. Federation introduces network dependencies and trust boundaries. Most vaults — especially local development and single-team use — never need it.