### Knoe configuration environments

Knoe treats `$KNOE_CONF` as an explicit set of deployment-specific configs.

#### Directory layout

Under `$KNOE_CONF`:

```text
$KNOE_CONF/k3d.cfg                   -> base config (k3d / dev)
$KNOE_CONF/k3s.cfg                   -> base config (k3s / service)
$KNOE_CONF/gke.cfg                   -> base config (k8s / prod)
$KNOE_CONF/test.cfg                  -> base config (test, optional)
```

Legacy layouts are still recognized for compatibility:

```text
$KNOE_CONF/knoe.cfg                 -> legacy entrypoint
$KNOE_CONF/<env>/knoe.cfg           -> legacy env base config
```

#### Activation (selecting the active environment)

- The active environment is inferred from `CLUSTER_ENV`, `KNOE_MODE`, or `DEPLOYMENT_MODE`.
- Resolution prefers named root files (`k3d.cfg`, `k3s.cfg`, `gke.cfg`) and only falls back to legacy `knoe.cfg` paths.
- Switching environments changes which named file is selected; it does not overwrite other environment configs.

If a legacy `knoe.cfg` regular file is detected, migration preserves it as `knoe.cfg.legacy.<timestamp>` and promotes content into the appropriate named file.

#### Override layering (deterministic merge)

- Named root configs (`k3d.cfg`, `k3s.cfg`, `gke.cfg`, `test.cfg`) are loaded directly.
- Legacy env-directory layout still supports layered `*.cfg` overrides in lexicographic filename order.

Later files override earlier values (last write wins).

#### Why this prevents accidental namespace drift

- k3d, k3s, and k8s/GKE are cleanly separated by dedicated config files.
- Mode/environment selection is explicit via deployment hints instead of mutable symlink state.
- Legacy configs remain readable during transition, reducing migration risk.