# Vault & Registry Configuration

Context Nest reads configuration from two places:

1. **Per-vault config** — `.context/config.yaml` inside each vault (vault name, layout, federation, source-server registry, telemetry).
2. **Central registry** — `~/.contextnest/config.yaml` in the user's home directory. This is a machine-wide registry that names vaults and remotes so you can refer to them by alias from anywhere.

## Central registry (`~/.contextnest/config.yaml`)

The central registry holds a `vaults:` map (alias → local vault), an optional `remotes:` map (alias → hosted / MCP nest connection), and a `default` alias. Entries are written by `ctx vault add`, so you rarely edit this file by hand.

```yaml
# ~/.contextnest/config.yaml

version: 1
default: work                     # default alias when none is specified

# Local vaults: alias -> { path, description? }
vaults:
  work:
    path: ~/my-vault
    description: "Primary vault"
  scratch:
    path: ~/scratch-vault

# Remote nests: alias -> connection (written by `ctx vault add --url|--mcp-command`)
remotes:
  team:
    transport: http
    url: "https://nest.example.com/mcp"    # send the bearer token over TLS
    auth:
      bearer_env: TEAM_NEST_TOKEN          # env-var NAME; the token is never stored
  legal:
    transport: stdio
    command: "contextnest-remote"
    args:
      - legal
```

The registry directory defaults to `~/.contextnest` and can be relocated with the `CONTEXTNEST_CONFIG_DIR` environment variable.

### Vaults

`vaults:` maps a short alias to a local vault so commands can target it by name (for example `--vault work`) instead of a full path. Each entry is an object with a `path` and an optional `description`. Register one with `ctx vault add <alias> <path>`.

### Remotes

`remotes:` maps an alias to a nest reached over MCP. Two transports are supported:

- **`http`** — a streamable-HTTP endpoint (`url`), with a bearer token read at call time from the env var named in `auth.bearer_env`. The token value itself is **never** written to the config; only the variable name is stored. If that variable is unset, the CLI errors with `CONFIG_ERROR` rather than calling out unauthenticated.
- **`stdio`** — a local MCP server spawned as `command` with `args`.

Register remotes with `ctx vault add <alias> --url … --bearer-env …` or `ctx vault add <alias> --mcp-command … --mcp-arg …`. See [Remote & Governed Nests](https://nest.promptowl.ai/d/promptowl-documents/protocol/remote-nests/remote-governed-nests).

## Resolution precedence

When a command needs to decide which vault to operate on, the engine's `resolveVaultPath` resolves in this order (first match wins):

1. **`--vault` flag** — an explicit registered alias on the command line.
2. **`CONTEXTNEST_VAULT` env var** — a registered vault **alias** from the environment.
3. **`CONTEXTNEST_VAULT_PATH` env var** — a direct vault **path** from the environment.
4. **An explicit path argument** — a path passed to the command.
5. **The current-working-directory vault** — the nearest vault found by walking up from `cwd` for a `.context/config.yaml`.
6. **`default:` in the central registry** — the default alias declared in `~/.contextnest/config.yaml`.
7. **Bare `cwd`** — the working directory as a last resort.

Note the two environment variables are distinct: `CONTEXTNEST_VAULT` names a **registered alias**, while `CONTEXTNEST_VAULT_PATH` is a **direct path**. Also note the **cwd/local vault is checked before the registry `default`** — a vault you are standing in wins over the configured default.

*Confirmed against the engine's `resolveVaultPath`; env-var names and this ordering are taken from that code.*

## Per-vault config (`.context/config.yaml`)

```yaml
name: "My Project"
namespace: "my-project"
layout: structured          # structured or obsidian
federation: none            # none, federated, or scoped

# Server registry for source nodes
servers:
  jira:
    url: "https://mycompany.atlassian.net"
    transport: mcp
  github:
    url: "https://api.github.com"
    transport: mcp
  slack:
    url: "https://slack.com/api"
    transport: rest

# Telemetry (opt-in, metadata only, never vault content)
telemetry: false
```

### Per-vault fields

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `name` | string | `"My Context Nest"` | Vault display name |
| `namespace` | string | — | Unique namespace for federation |
| `layout` | string | `structured` | `structured` or `obsidian` |
| `federation` | string | `none` | `none`, `federated`, or `scoped` |
| `servers` | object | — | Server registry for source nodes |
| `telemetry` | boolean | `false` | Opt-in anonymous usage telemetry |

## Environment variables

| Variable | Description |
|----------|-------------|
| `CONTEXTNEST_VAULT` | Registered vault **alias** to use (see resolution precedence) |
| `CONTEXTNEST_VAULT_PATH` | Direct vault **path** override (see resolution precedence) |
| `CONTEXTNEST_CONFIG_DIR` | Override the registry directory (default `~/.contextnest`) |
| `PROMPTOWL_API_URL` | Override cloud API URL (default `https://app.promptowl.ai`) |
| `CONTEXTNEST_API_KEY` | `cnst_…` key `ctx push` sends to the hosted server when `--key` is not given |
| *(per-remote bearer var)* | The env var named by a remote's `auth.bearer_env`, holding that remote's bearer token |

## CONTEXT.md

The `CONTEXT.md` file at the vault root is a free-form markdown file that serves as the vault-level system prompt. AI agents read it first before accessing individual documents.

Write it to describe:
- What the vault is for
- How the agent should interact with it
- Any conventions or rules specific to your team

## Related

- [Vault Registry & Multi-Vault](https://nest.promptowl.ai/d/promptowl-documents/protocol/vault-registry/vault-registry-multi-vault) — managing aliases with `ctx vault`
- [Remote & Governed Nests](https://nest.promptowl.ai/d/promptowl-documents/protocol/remote-nests/remote-governed-nests) — the `remotes:` map in practice
- [CLI Reference](https://nest.promptowl.ai/d/promptowl-documents/protocol/cli-reference) — the `ctx` command surface
- [Authentication & API Keys](https://nest.promptowl.ai/d/promptowl-documents/protocol/authentication-api-keys) — `cnst_` keys for push and remotes