# How Configuration Key Ownership and Documentation Inheritance Work in no-mistakes

> Learn how no-mistakes handles configuration key ownership and documentation inheritance with its shallow merge strategy. Discover how repository settings override global defaults while preserving documentation.

- Repository: [Kun Chen/no-mistakes](https://github.com/kunchenguid/no-mistakes)
- Tags: internals
- Published: 2026-07-12

---

**no-mistakes treats every configuration option as a first-class fact with a single authoritative documentation source, using a shallow merge strategy where repository-specific settings in [`.no-mistakes.yaml`](https://github.com/kunchenguid/no-mistakes/blob/main/.no-mistakes.yaml) override global defaults from `~/.no-mistakes/config.yaml` while preserving documentation ownership.**

The `no-mistakes` configuration system enforces strict **configuration key ownership** to prevent documentation drift and implementation inconsistencies. Each setting exists as a first-class fact tied to a specific documentation file, ensuring that definitions, types, and defaults remain synchronized across the codebase. This design combines explicit ownership rules with a hierarchical inheritance model that lets repositories customize behavior without duplicating entire configuration schemas.

## Understanding Configuration Key Ownership

### Global Configuration Keys

Global keys residing in `~/.no-mistakes/config.yaml` are owned by [`docs/reference/global-config.md`](https://github.com/kunchenguid/no-mistakes/blob/main/docs/reference/global-config.md) (located at [`docs/src/content/docs/reference/global-config.md`](https://github.com/kunchenguid/no-mistakes/blob/main/docs/src/content/docs/reference/global-config.md)). This file serves as the master reference for all global configuration keys, defining their defaults, types, and descriptions as implemented in [`internal/config/config.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/config/config.go).

### Repository-Specific Keys

Per-repository settings in [`.no-mistakes.yaml`](https://github.com/kunchenguid/no-mistakes/blob/main/.no-mistakes.yaml) files are owned by [`docs/reference/repo-config.md`](https://github.com/kunchenguid/no-mistakes/blob/main/docs/reference/repo-config.md) (at [`docs/src/content/docs/reference/repo-config.md`](https://github.com/kunchenguid/no-mistakes/blob/main/docs/src/content/docs/reference/repo-config.md)). When a repository provides its own configuration, the daemon loads the trusted default-branch copy of that file to apply overrides, ensuring that changes undergo proper review before affecting runtime behavior.

### Environment Variables

Environment-based configuration is owned by [`docs/reference/environment.md`](https://github.com/kunchenguid/no-mistakes/blob/main/docs/reference/environment.md) (at [`docs/src/content/docs/reference/environment.md`](https://github.com/kunchenguid/no-mistakes/blob/main/docs/src/content/docs/reference/environment.md)), which catalogs all environment variables affecting the daemon and client behavior according to the source definitions in [`internal/config/config.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/config/config.go).

### Enforcement Through Drift Tests

The ownership rule is enforced by comment blocks and CI drift tests that validate synchronization between documentation and the struct definitions in [`internal/config/config.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/config/config.go). If a new key is added without updating the corresponding documentation file, the CI pipeline fails, preventing documentation rot.

## How Configuration Inheritance Works

### The Shallow Merge Strategy

Inheritance operates through a **shallow merge** that preserves the documentation ownership hierarchy. The system starts with global defaults, then applies repository-specific overrides for only the fields explicitly set in the repo config. Unspecified keys automatically inherit global values, maintaining their original documentation sources.

### Loading Order and Precedence

The loading sequence follows three distinct steps:

1. Load global defaults from `~/.no-mistakes/config.yaml`
2. Load the default-branch copy of [`.no-mistakes.yaml`](https://github.com/kunchenguid/no-mistakes/blob/main/.no-mistakes.yaml) from the repository
3. Merge the repository configuration on top of global defaults using shallow key replacement

### Practical Configuration Example

Consider the following global configuration:

```yaml

# ~/.no-mistakes/config.yaml (owned by docs/reference/global-config.md)

agent: auto
auto_fix:
  rebase: 3
  review: 0
  test: 3
  lint: 3

```

A repository can override specific values without redefining the entire schema:

```yaml

# .no-mistakes.yaml (owned by docs/reference/repo-config.md)

auto_fix:
  rebase: 1
agent: codex

```

The resulting merged configuration preserves inherited values while applying overrides:

```yaml
agent: codex          # From repo config

auto_fix:
  rebase: 1           # From repo config

  review: 0           # Inherited from global

  test: 3             # Inherited from global

  lint: 3             # Inherited from global

```

## Source Files and Documentation Hierarchy

The following files implement and document the ownership model:

- **[`internal/config/config.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/config/config.go)**: Contains struct definitions and loading logic for global and repository configurations.
- **[`docs/src/content/docs/reference/global-config.md`](https://github.com/kunchenguid/no-mistakes/blob/main/docs/src/content/docs/reference/global-config.md)**: Master reference and **owner** of all global configuration keys.
- **[`docs/src/content/docs/reference/repo-config.md`](https://github.com/kunchenguid/no-mistakes/blob/main/docs/src/content/docs/reference/repo-config.md)**: Reference and **owner** of per-repository configuration overrides.
- **[`docs/src/content/docs/reference/environment.md`](https://github.com/kunchenguid/no-mistakes/blob/main/docs/src/content/docs/reference/environment.md)**: Reference and **owner** of environment variables affecting the daemon.
- **[`AGENTS.md`](https://github.com/kunchenguid/no-mistakes/blob/main/AGENTS.md)** (repository root): Documents high-level ownership conventions across the codebase.

## Summary

- **Configuration key ownership** assigns each setting to a specific documentation file, preventing drift between code and docs.
- Global keys reside in `~/.no-mistakes/config.yaml` and are owned by [`docs/reference/global-config.md`](https://github.com/kunchenguid/no-mistakes/blob/main/docs/reference/global-config.md).
- Repository keys in [`.no-mistakes.yaml`](https://github.com/kunchenguid/no-mistakes/blob/main/.no-mistakes.yaml) are owned by [`docs/reference/repo-config.md`](https://github.com/kunchenguid/no-mistakes/blob/main/docs/reference/repo-config.md).
- **Shallow merge** inheritance applies repo overrides atop global defaults without requiring schema duplication.
- Drift tests in CI enforce that [`internal/config/config.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/config/config.go) structs remain synchronized with their documentation owners.

## Frequently Asked Questions

### What happens if a repository doesn't define a [`.no-mistakes.yaml`](https://github.com/kunchenguid/no-mistakes/blob/main/.no-mistakes.yaml) file?

If no repository-specific configuration exists, the system uses only the global defaults from `~/.no-mistakes/config.yaml`. All settings inherit their values and documentation from the global configuration owner without requiring an empty configuration file.

### How does no-mistakes prevent documentation from becoming outdated?

The codebase includes drift tests that compare struct definitions in [`internal/config/config.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/config/config.go) against the owned documentation files. CI fails if a configuration key exists in code but lacks corresponding documentation updates in the assigned reference file, ensuring single-source-of-truth maintenance.

### Can environment variables override repository configuration values?

Yes, environment variables documented in [`docs/src/content/docs/reference/environment.md`](https://github.com/kunchenguid/no-mistakes/blob/main/docs/src/content/docs/reference/environment.md) can affect daemon and client behavior. The inheritance hierarchy typically resolves such that explicit file-based configurations combine with environment overrides according to the specific loading implementation in [`internal/config/config.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/config/config.go).

### Why does the system load the default-branch copy of the repo config?

Loading the trusted default-branch version of [`.no-mistakes.yaml`](https://github.com/kunchenguid/no-mistakes/blob/main/.no-mistakes.yaml) ensures that configuration changes undergo proper review through the version control workflow before affecting the daemon's behavior. This prevents unreviewed local modifications from impacting operations while maintaining the integrity of the ownership model.