# Cluster configuration reference

`--config` defaults to the current directory. Unknown fields and duplicate YAML keys are errors so that misspelled intent is never ignored.

## Configuration Commands

`--config DIR` reads desired configuration from a directory containing `cluster.yaml`. `--target NAME|ADDRESS` separately selects the backend for plan, apply and observation. Validation needs only source files:

```
omnigraph cluster validate --config ./company-brain
```

## Complete shape

```
version: 1

metadata:
  name: company-brain

# Optional assertion: must match the selected target for plan/apply.
storage: s3://company-data/omnigraph/company-brain

state:
  backend: cluster
  lock: true

providers:
  embedding:
    default:
      kind: openai-compatible
      base_url: https://api.example.com/v1
      model: text-embedding-3-large
      api_key: ${EMBEDDING_API_KEY}

graphs:
  knowledge:
    schema: knowledge.pg
    queries: queries/
    embedding_provider: default
    external_blobs:
      allow:
        - base: s3://company-assets/knowledge/
          scope: server_safe

policies:
  graph-access:
    file: graph.policy.yaml
    applies_to: [knowledge]
  server-access:
    file: server.policy.yaml
    applies_to: [cluster]
```

## Top-level fields

| Field | Required | Meaning |
| --- | --- | --- |
| `version` | yes | Configuration schema; currently `1` |
| `metadata.name` | no | Display name |
| `storage` | no | Optional root assertion; must match the selected target for direct or server plan/apply |
| `state.backend` | no | Omit or set to `cluster` |
| `state.lock` | no | Exclusive writer admission; omit or set to `true`; `false` refuses execution |
| `providers.embedding` | no | Named embedding provider profiles |
| `graphs` | no | Graph declarations keyed by graph ID |
| `policies` | no | Policy bundles keyed by bundle name |

## Graphs

Each graph requires a schema file:

```
graphs:
  knowledge:
    schema: knowledge.pg
```

Optional fields:

| Field | Meaning |
| --- | --- |
| `queries` | Stored-query files, directories, or explicit name mappings |
| `embedding_provider` | Name under `providers.embedding` |
| `external_blobs` | Allow-list for new external Blob references |

## Embedding providers

Provider `kind` may be `openai-compatible`, `openai`, `gemini`, or `mock`. Real providers require `api_key: ${ENVIRONMENT_VARIABLE}`; inline secrets are rejected. The serving process resolves the environment variable at boot and during live deployment preflight for affected graphs.

## External Blob references

New external references are denied unless their normalized URI falls under an allowed base:

```
external_blobs:
  allow:
    - base: s3://company-assets/knowledge/
      scope: server_safe
```

## Policies

```
policies:
  graph-access:
    file: graph.policy.yaml
    applies_to: [knowledge, catalog]
  registry-access:
    file: server.policy.yaml
    applies_to: [cluster]
```

## Storage

Plan and apply always use the selected direct-root or server target. Omitting `storage` makes the bundle portable between explicitly selected destinations.

## Declared paths

Every `schema`, `queries`, and policy `file` path is resolved against the directory that holds `cluster.yaml`. A relative path must stay inside that directory.

## Command behavior

| Command | Changes graph or cluster state? | Use |
| --- | --- | --- |
| `validate` | no | Parse and type-check the declaration |
| `plan` | no | Preview desired differences; unsupported deployment effects still refuse |
| `apply` | yes | Converge graph inventory, schemas, queries, policies and provider/Blob settings |
| `status` | no | Read recorded deployment and lock status; server status also observes activation |
| `observe` | no | Report current observations without changing authority |
| `force-unlock` | yes | Remove one proven-stale lock by exact ID |
| `upgrade-ledger` | state only | Convert a stopped legacy ledger without resetting graph data |

## Limits

| Resource | Limit |
| --- | --- |
| Each `cluster.yaml`, schema, query or policy source | 1 MiB |
| Distinct source bytes in one captured bundle | 8 MiB |
| Declared resources (each graph and schema count separately) | 4096 |
| Query discovery paths plus directory entries, including ignored files | 4096 |
| Encoded immutable deployment bundle | 16 MiB |
| Encoded cluster ledger | 16 MiB |
| Lock metadata read | 64 KiB |
| Outstanding deployments | 1 |
| Retained deployment results | 32 records, 4 MiB total, 1 MiB each |
| Deployment actor / resource address / canonical root | 256 / 512 / 4096 UTF-8 bytes |

## Operator targets

The operator file declares destinations separately from this source bundle.
