Skip to content

The agent that grows with you

docs(config): move the config backend seam's long form into developer-guide/config-backend.md

Ben Barclay659de11cdaf2
diff --git a/hermes_cli/AGENTS.md b/hermes_cli/AGENTS.md
index fcfcee48b99..8b8478d5e33 100644
--- a/hermes_cli/AGENTS.md
+++ b/hermes_cli/AGENTS.md
@@ -90,19 +90,12 @@ set/get/unset <NAME>` route any bare name registered in `OPTIONAL_ENV_VARS` / `_
- **One writer seam.** Every write of a `config.yaml` (main or profile) goes through
`hermes_cli.config.atomic_config_write` (refuses deletion by omission) or the explicit
`atomic_config_replace` full-state path (→ `utils.atomic_roundtrip_yaml_save`, ruamel
- round-trip): comments, key order, quoting and blank lines survive, and the fail-closed unreadable-file
- guard runs first. Deliberate `pop()`/unset/migration paths use `atomic_config_replace`; additive
+ round-trip): formatting survives, and the fail-closed unreadable-file guard runs first. Deliberate `pop()`/unset/migration paths use `atomic_config_replace`; additive
writers stay on `atomic_config_write`. Never call
`atomic_yaml_write` / `yaml.dump` / `yaml.safe_dump` on a config path — `scripts/check_config_yaml_writers.py`
(CI lint) rejects it, and `tests/hermes_cli/test_config_yaml_comment_preservation.py` guards each
path (#92554). The commented example blocks are appended only when the file is created.
-- **Config backend seam:** every read, stat, existence check and write of a user `config.yaml`
- goes through `hermes_cli/config_backend.py` (`read_config_doc`, `read_config_doc_readonly`,
- `config_version`, `config_exists`, `write_config_key`, `write_config_document`). The backend
- is chosen by `HERMES_CONFIG_BACKEND` only (default `file`; never by a config value). Tools that
- copy, edit or back up the file itself check `supports_file_tooling()` first.
- `scripts/check_config_yaml_readers.py` (CI lint) rejects a direct `open`/`read_text`/`stat`/
- `exists`/YAML load of a config path; mark a true false positive `# config-reader: ok — <why>`.
+- **Reads** too go only through `config_backend.py`; see `developer-guide/config-backend.md`.
- **Three loaders — know which you're in:** `load_cli_config()` (CLI, `cli.py`); `load_config()`
(`hermes tools/setup`, most subcommands, `hermes_cli/config.py`, merges `DEFAULT_CONFIG`);
`hermes_cli/config_effective.py::load_user_config_effective()` (gateway runtime via
diff --git a/website/docs/developer-guide/config-backend.md b/website/docs/developer-guide/config-backend.md
new file mode 100644
index 00000000000..d9e4c6faa29
--- /dev/null
+++ b/website/docs/developer-guide/config-backend.md
@@ -0,0 +1,35 @@
+---
+sidebar_position: 12
+title: "Config Backend Seam"
+description: "Where a profile's user config.yaml is read and written: the ConfigBackend seam, the file and remote backends, and the CI lints that keep every caller on it"
+---
+
+# Config Backend Seam
+
+Every read, stat, existence check and write of a profile's user `config.yaml` goes through
+`hermes_cli/config_backend.py`. The backend is chosen once per process from
+`HERMES_CONFIG_BACKEND`, never from a config value: `file` is the default, and `remote` is
+[Remote Config](../user-guide/remote-config.md) (`plugins/config_backends/remote/`).
+
+## Helpers
+
+| Helper | Use |
+|---|---|
+| `read_config_doc(path)` | Parsed user layer (raises like `open` + `fast_safe_load`) |
+| `read_config_doc_readonly(path)` | Signature-cached read; never mutate the result |
+| `config_version(path)` | Cache signature (the file's stat tuple, or the remote version) |
+| `config_exists(path)` | Whether the layer exists (a remote layer always does) |
+| `write_config_document(path, doc)` / `write_config_key(path, key, value)` | Writes; callers normally use `atomic_config_write` / `atomic_config_replace` |
+| `supports_file_tooling()` / `require_file_tooling(what)` | Gate for tools that copy, edit or back up the file itself (`config edit`, backup/restore, profile clone) |
+
+Caches keyed on `config_version` miss when a remote poll installs a new layer, exactly as
+they do after a local file edit. The managed scope (`/etc/hermes`) stays an overlay on top
+of whatever user layer the backend returns.
+
+## Lints
+
+- `scripts/check_config_yaml_writers.py` rejects a direct YAML dump of a config path.
+- `scripts/check_config_yaml_readers.py` rejects a direct `open` / `read_text` / `stat` /
+ `exists` / YAML load of a config path. A true false positive (another product's config
+ file, or file tooling already gated on `supports_file_tooling()`) carries
+ `# config-reader: ok — <why>` on the line.
diff --git a/website/sidebars.ts b/website/sidebars.ts
index 8585fa5a9a8..0b6a05597fb 100644
--- a/website/sidebars.ts
+++ b/website/sidebars.ts
@@ -803,6 +803,7 @@ const sidebars: SidebarsConfig = {
'developer-guide/session-storage',
'developer-guide/state-db-recovery',
'developer-guide/provider-runtime',
+ 'developer-guide/config-backend',
'developer-guide/programmatic-integration',
],
},