features/settings_configuration.feature

@@ -2,6 +2,17 @@ Feature: Settings runtime helpers
   Verify environment alias, storage paths, database URLs, production flags,
   provider configuration lookups, and LangSmith config guards behave predictably.
 
+  Scenario: data_dir default is the spec-required home directory path
+    Given no environment variables are set
+    When I load the settings with defaults
+    Then the data directory should equal the home cleveragents path
+
+  Scenario: data_dir env var override takes precedence over default
+    Given no environment variables are set
+    And the environment variable "CLEVERAGENTS_DATA_DIR" is set to "/tmp/custom-data"
+    When I load the settings with defaults
+    Then the data directory should be "/tmp/custom-data"
+
   Scenario: Environment alias setter syncs env field
     Given no environment variables are set
     When I load the settings with defaults

features/steps/settings_steps.py

@@ -104,6 +104,15 @@ def step_check_log_dir_contains(context, substring):
     assert substring in str(context.settings.log_dir)
 
 
+@then("the data directory should equal the home cleveragents path")
+def step_check_data_dir_home_cleveragents(context):
+    """Check that data_dir defaults to Path.home() / '.cleveragents'."""
+    expected = Path.home() / ".cleveragents"
+    assert context.settings.data_dir == expected, (
+        f"Expected data_dir={expected!r}, got {context.settings.data_dir!r}"
+    )
+
+
 @then('the data directory should be "{expected}"')
 def step_check_data_dir(context, expected):
     """Check the data directory."""

src/cleveragents/config/settings.py

@@ -130,7 +130,7 @@ class Settings(BaseSettings):
         validation_alias=AliasChoices("CLEVERAGENTS_LOG_DIR"),
     )
     data_dir: Path = Field(
-        default_factory=lambda: Path("data"),
+        default_factory=lambda: Path.home() / ".cleveragents",
         validation_alias=AliasChoices("CLEVERAGENTS_DATA_DIR"),
     )
     storage_base_path: Path = Field(