document config overlay more

doc/cli-reference.md

@@ -97,6 +97,13 @@ Active runtime config is built in this order:
 2. optional `--config` JSON overlay
 3. explicit CLI overrides
 
+Overlay semantics:
+- mappings merge recursively
+- lists replace the baseline list wholesale
+- omitted fields inherit model defaults
+
+The packaged files under `speakeasy/configs/*.json` are ordinary overlays. They are not selected automatically.
+
 Conflict example:
 
 ```bash

doc/configuration.md

@@ -390,10 +390,17 @@ Runtime precedence:
 2. optional `--config` overlay
 3. explicit CLI flags
 
+Overlay semantics:
+- mappings merge recursively
+- lists replace the baseline list wholesale
+- omitted fields inherit model defaults
+
 `--volume` is a dedicated shortcut for filesystem mappings and is applied before schema-derived CLI overrides.
 
 Use `--dump-default-config` to emit the built-in default profile.
 
+The packaged files under `speakeasy/configs/*.json` are ordinary config overlays. They are not selected automatically or treated specially by the runtime.
+
 Complex nested structures remain config-file-only (for example `filesystem.files`, `registry.keys`, `processes`, `modules.user_modules`, `modules.system_modules`, and structured network response lists).
 
 ## Operational notes

tests/test_cli_config.py

@@ -41,3 +41,26 @@ def test_dump_default_config_flag_outputs_valid_json():
 
     assert model.timeout == 60
     assert model.max_api_count == 10000
+
+
+def test_partial_config_overlay_inherits_model_defaults():
+    model = SpeakeasyConfig.model_validate({"analysis": {"memory_tracing": True}})
+
+    assert model.analysis.memory_tracing is True
+    assert model.analysis.strings is True
+    assert model.os_ver.major == 6
+    assert model.modules.user_modules
+
+
+def test_merge_config_dicts_merges_mappings_and_replaces_lists():
+    base = get_default_config_dict()
+    overlay = {
+        "analysis": {"memory_tracing": True},
+        "processes": [{"name": "only", "base_addr": "0x00400000", "path": "C:\\only.exe"}],
+    }
+
+    merged = merge_config_dicts(base, overlay)
+
+    assert merged["analysis"]["memory_tracing"] is True
+    assert merged["analysis"]["strings"] is True
+    assert merged["processes"] == overlay["processes"]