# .antil/local.yaml

`.antil/local.yaml` is an optional Workspace-local overlay, read after `antil.yaml`. It accepts exactly the [version 1 schema](/docs/reference/configuration/), with no additional local-only YAML keys. Defaults are applied after merging. An overlay need not repeat required fields supplied by the project file.

## keys and defaults

| key family | type | default in overlay | example |
| --- | --- | --- | --- |
| `version`, `project`, `target` | same scalars as project config | inherited | `target: main` |
| `services` | map, full Service schema | inherited / empty when newly added | `web: {timeout: 30s}` |
| `stacks` | map, `services` list per entry | inherited | `default: {services: [web]}` |
| `resources` | map, full Resource schema | inherited / Resource defaults for new entries | `db: {sharing: private}` |
| `operations` | map, full OperationDefinition schema | inherited | `test: {timeout: 30s}` |
| `rules` | map, full Rule schema | inherited | `migrations: {paths: ["schema/**"]}` |

All child keys, types and defaults are identical to those in the `antil.yaml` reference.

## merge semantics

| value | behavior |
| --- | --- |
| map | merge by key |
| scalar or list | replace the previous value; lists do not append |
| `null` | delete the key, then validate the merged config and apply defaults |
| Service `ready` or `port` | replace the whole definition |
| one Service or operation env entry | replace the whole literal / secret / Resource reference |

Duplicate keys are rejected in each input layer even if a later overlay would replace them. Unknown fields are invalid in the effective schema. Probe and port definitions do not partially merge.

## example

```yaml
services:
  web:
    timeout: 30s
    env:
      TOKEN: {secret: .antil/token}
      MODE: development
```

A secret reference resolves at dispatch. `config explain` returns references and each effective value's source file and line. Keep `.antil/` excluded from git. Local overlays participate in the effective config revision; they do not replan an existing Session.