The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
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.mdindex 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`; additivewriters 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 eachpath (#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 viadiff --git a/website/docs/developer-guide/config-backend.md b/website/docs/developer-guide/config-backend.mdnew file mode 100644index 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.tsindex 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',],},