From e876b569b7db482c8bd1543d9ddf4a1901cf375d Mon Sep 17 00:00:00 2001
From: rzx <ruanzhengxin.rzx@alibaba-inc.com>
Date: Tue, 19 May 2026 18:59:07 +0800
Subject: [PATCH] feat: add IAC_CODE_CONFIG_DIR & fix A2A not loading
 persistence on restart

- Add `IAC_CODE_CONFIG_DIR` env var to relocate the runtime config
  dir (default `~/.iac-code/`); all persisted artifacts follow it.
- Fix A2A server losing session state across restarts: restore the
  persisted `session_id` from `A2APersistenceStore` and resume prior
  messages from `SessionStorage`.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 AGENTS.md                                     |   2 +-
 src/iac_code/a2a/executor.py                  |  22 ++-
 src/iac_code/a2a/task_store.py                |  11 +-
 src/iac_code/config.py                        |  29 ++-
 src/iac_code/providers/registry.py            |   2 +-
 src/iac_code/services/agent_factory.py        |   2 +
 src/iac_code/skills/discovery.py              |   6 +-
 tests/a2a/test_executor.py                    |  79 +++++++-
 tests/a2a/test_task_store.py                  |  32 ++++
 tests/conftest.py                             |   4 +
 tests/skills/test_discovery.py                |  22 +++
 tests/test_config_dir_env.py                  | 174 ++++++++++++++++++
 .../configuration/environment-variables.md    |   1 +
 .../configuration/runtime-configuration.md    |   4 +-
 .../configuration/environment-variables.md    |   1 +
 .../configuration/runtime-configuration.md    |   4 +-
 .../configuration/environment-variables.md    |   1 +
 .../configuration/runtime-configuration.md    |   4 +-
 .../configuration/environment-variables.md    |   1 +
 .../configuration/runtime-configuration.md    |   4 +-
 .../configuration/environment-variables.md    |   1 +
 .../configuration/runtime-configuration.md    |   4 +-
 .../configuration/environment-variables.md    |   1 +
 .../configuration/runtime-configuration.md    |   4 +-
 .../configuration/environment-variables.md    |   1 +
 .../configuration/runtime-configuration.md    |   4 +-
 26 files changed, 399 insertions(+), 21 deletions(-)
 create mode 100644 tests/test_config_dir_env.py

diff --git a/AGENTS.md b/AGENTS.md
index 72fb0656..d1aa15d2 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -43,7 +43,7 @@ Prefer using `uv` and existing Makefile targets. When adding new dependencies, u
 
 ## Configuration and Credentials
 
-- The runtime configuration directory is `~/.iac-code/`, containing `.credentials.yml`, `.cloud-credentials.yml`, `settings.yml`, and input history.
+- The runtime configuration directory defaults to `~/.iac-code/`, containing `.credentials.yml`, `.cloud-credentials.yml`, `settings.yml`, `.multimodal-cache.yml`, and input history. Override by setting `IAC_CODE_CONFIG_DIR` (supports `~` and `$VAR` expansion); all subdirectories (`projects/`, `image-cache/`, `tool-results/`, `logs/`, `memory/`, `a2a/`, `telemetry/`, `skills/`) follow.
 - Do not commit, print, or hard-code real API keys, AccessKeys, Secrets, tokens, cookies, or user configuration file contents.
 - Alibaba Cloud credential-related tests must use fake values and avoid triggering real cloud APIs.
 
diff --git a/src/iac_code/a2a/executor.py b/src/iac_code/a2a/executor.py
index cbb0233a..8d2d292d 100644
--- a/src/iac_code/a2a/executor.py
+++ b/src/iac_code/a2a/executor.py
@@ -25,6 +25,7 @@
     TASK_STATE_WORKING,
 )
 from iac_code.services.agent_factory import AgentFactoryOptions, create_agent_runtime
+from iac_code.services.session_storage import SessionStorage
 
 logger = logging.getLogger(__name__)
 _CONTEXT_LOCK_ACQUIRE_TIMEOUT_SECONDS = 1
@@ -117,7 +118,19 @@ async def execute(self, context: RequestContext, event_queue: EventQueue) -> Non
             return
 
         def runtime_factory(session_id: str) -> Any:
-            return create_agent_runtime(AgentFactoryOptions(model=self._model, session_id=session_id, cwd=cwd))
+            session_storage = SessionStorage()
+            resume_messages = None
+            if session_storage.exists(cwd, session_id):
+                loaded = session_storage.load(cwd, session_id)
+                resume_messages = SessionStorage.repair_interrupted(loaded) if loaded else None
+            return create_agent_runtime(
+                AgentFactoryOptions(
+                    model=self._model,
+                    session_id=session_id,
+                    cwd=cwd,
+                    resume_messages=resume_messages,
+                )
+            )
 
         try:
             ctx = await self._task_store.get_or_create_context(
@@ -296,11 +309,16 @@ def _resolve_cwd(self, metadata: Any | None) -> str:
                 raw_cwd = raw_iac_meta.get("cwd")
                 if isinstance(raw_cwd, str):
                     cwd = raw_cwd
-        if not isinstance(cwd, str) or not Path(cwd).is_absolute() or not Path(cwd).is_dir():
+        if not isinstance(cwd, str) or not Path(cwd).is_absolute():
             raise ValueError("Invalid A2A workspace metadata.")
         resolved_cwd = Path(cwd).resolve()
         if not any(_is_relative_to(resolved_cwd, root) for root in _allowed_cwd_roots()):
             raise ValueError("Invalid A2A workspace metadata.")
+        if resolved_cwd.exists():
+            if not resolved_cwd.is_dir():
+                raise ValueError("Invalid A2A workspace metadata.")
+        else:
+            resolved_cwd.mkdir(parents=True, exist_ok=True)
         return str(resolved_cwd)
 
     def _prompt_from_context(self, context: RequestContext, *, cwd: str) -> str:
diff --git a/src/iac_code/a2a/task_store.py b/src/iac_code/a2a/task_store.py
index d99e7647..a1deb8dd 100644
--- a/src/iac_code/a2a/task_store.py
+++ b/src/iac_code/a2a/task_store.py
@@ -160,7 +160,16 @@ async def get_or_create_context(
                 self._mirror_context(record)
                 return record
 
-            session_id = str(uuid.uuid4())
+            session_id: str | None = None
+            if self._persistence is not None:
+                snapshot = self._persistence.load_context(context_id)
+                if snapshot is not None:
+                    if snapshot.cwd != cwd:
+                        raise ValueError("A2A context belongs to a different workspace")
+                    session_id = snapshot.session_id
+
+            if session_id is None:
+                session_id = str(uuid.uuid4())
             record = A2AContextRecord(
                 context_id=context_id,
                 session_id=session_id,
diff --git a/src/iac_code/config.py b/src/iac_code/config.py
index cdc6d621..7ece856b 100644
--- a/src/iac_code/config.py
+++ b/src/iac_code/config.py
@@ -1,11 +1,14 @@
 """Configuration paths for iac-code.
 
 Provides unified configuration directory and file paths under
-``~/.iac-code/``.
+``~/.iac-code/`` by default. Can be relocated by setting the
+``IAC_CODE_CONFIG_DIR`` environment variable (``~`` and ``$VAR``
+expansion supported); when set, every persisted artifact follows.
 """
 
 from __future__ import annotations
 
+import os
 from pathlib import Path
 from typing import Any
 
@@ -16,6 +19,7 @@
 
 # Configuration directory
 _CONFIG_DIR_NAME = ".iac-code"
+_CONFIG_DIR_ENV_VAR = "IAC_CODE_CONFIG_DIR"
 
 # Configuration files
 _CREDENTIALS_FILE = ".credentials.yml"
@@ -125,7 +129,6 @@ def _get_env_overrides() -> dict[str, str | None]:
     to None. Invalid ``IAC_CODE_PROVIDER`` raises ``ValueError`` listing canonical
     names.
     """
-    import os
 
     def _read(name: str) -> str | None:
         raw = os.environ.get(name, "")
@@ -171,12 +174,28 @@ def get_llm_source() -> str:
 # ---------------------------------------------------------------------------
 
 
+def _resolve_config_dir() -> Path:
+    """Resolve the config directory path without creating it.
+
+    Honors ``IAC_CODE_CONFIG_DIR`` (with ``~`` and ``$VAR`` expansion).
+    Empty / whitespace-only values are treated as unset.
+    """
+    raw = os.environ.get(_CONFIG_DIR_ENV_VAR, "").strip()
+    if raw:
+        expanded = os.path.expandvars(os.path.expanduser(raw))
+        return Path(expanded).resolve()
+    return Path.home() / _CONFIG_DIR_NAME
+
+
 def get_config_dir() -> Path:
-    """Get iac-code config directory (~/.iac-code/).
+    """Get iac-code config directory.
 
-    Creates the directory if it doesn't exist.
+    Defaults to ``~/.iac-code/``. Can be overridden by the
+    ``IAC_CODE_CONFIG_DIR`` environment variable. The directory is
+    created if it does not exist; this is read on every call (no
+    caching).
     """
-    config_dir = Path.home() / _CONFIG_DIR_NAME
+    config_dir = _resolve_config_dir()
     config_dir.mkdir(parents=True, exist_ok=True)
     return config_dir
 
diff --git a/src/iac_code/providers/registry.py b/src/iac_code/providers/registry.py
index b2edb2ce..d458d0a8 100644
--- a/src/iac_code/providers/registry.py
+++ b/src/iac_code/providers/registry.py
@@ -75,7 +75,7 @@ def model_ids(self) -> list[str]:
             ModelEntry("glm-5"),
             ModelEntry("MiniMax-M2.5"),
             ModelEntry("kimi-k2.5", support_multimodal=True),
-            ModelEntry("kimi-k2.6", support_multimodal=True)
+            ModelEntry("kimi-k2.6", support_multimodal=True),
         ],
         qwenpaw_provider_ids=["aliyun-tokenplan"],
     ),
diff --git a/src/iac_code/services/agent_factory.py b/src/iac_code/services/agent_factory.py
index 42bca50c..4f1a26a6 100644
--- a/src/iac_code/services/agent_factory.py
+++ b/src/iac_code/services/agent_factory.py
@@ -15,6 +15,7 @@ class AgentFactoryOptions:
     cli_allowed_tools: list[str] | None = None
     cli_disallowed_tools: list[str] | None = None
     cli_permission_mode: str | None = None
+    resume_messages: list | None = None
 
 
 @dataclass
@@ -162,6 +163,7 @@ def create_agent_runtime(options: AgentFactoryOptions) -> AgentRuntime:
         tool_registry=tool_registry,
         session_storage=session_storage,
         session_id=session_id,
+        resume_messages=options.resume_messages,
         max_turns=options.max_turns,
         cwd=cwd,
         permission_context=permission_context,
diff --git a/src/iac_code/skills/discovery.py b/src/iac_code/skills/discovery.py
index 4ae8b3fd..a0e9a208 100644
--- a/src/iac_code/skills/discovery.py
+++ b/src/iac_code/skills/discovery.py
@@ -6,6 +6,7 @@
 from pathlib import Path
 
 from iac_code.commands.registry import PromptCommand
+from iac_code.config import get_config_dir
 from iac_code.skills.loader import load_skill_from_path
 from iac_code.skills.skill_definition import SkillDefinition
 from iac_code.types.skill_source import SkillSource
@@ -16,7 +17,8 @@ def discover_all_skills(cwd: str) -> list[SkillDefinition]:
 
     Load order (later entries override earlier with same name):
     1. Bundled skills
-    2. User global skills (~/.iac-code/skills/)
+    2. User global skills (``<config-dir>/skills/``; defaults to
+       ``~/.iac-code/skills/``, follows ``IAC_CODE_CONFIG_DIR``)
     3. Project local skills — skills/ (lower priority)
     4. Project local skills — .iac-code/skills/ (higher priority, overrides same name)
     """
@@ -29,7 +31,7 @@ def discover_all_skills(cwd: str) -> list[SkillDefinition]:
         skills[skill.name] = skill
 
     # 2. User global skills
-    user_skills_dir = Path.home() / ".iac-code" / "skills"
+    user_skills_dir = get_config_dir() / "skills"
     for skill in _scan_skills_dir(user_skills_dir):
         skill.source = SkillSource.USER
         skills[skill.name] = skill
diff --git a/tests/a2a/test_executor.py b/tests/a2a/test_executor.py
index 87d01e1d..fd7c27f8 100644
--- a/tests/a2a/test_executor.py
+++ b/tests/a2a/test_executor.py
@@ -226,11 +226,31 @@ async def run_streaming(self, prompt: str):
 
 
 @pytest.mark.asyncio
-async def test_executor_rejects_invalid_workspace(tmp_path: Path) -> None:
+async def test_executor_creates_missing_workspace(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    runtime = FakeRuntime(agent_loop=FakeAgentLoop([TextDeltaEvent(text="hi")]), session_id="session-1")
+    monkeypatch.setattr("iac_code.a2a.executor.create_agent_runtime", lambda options: runtime)
+
+    missing = tmp_path / "missing"
     store = A2ATaskStore(metrics=NoOpA2AMetrics())
     executor = IacCodeA2AExecutor(task_store=store, model="qwen3.6-plus")
     queue = FakeEventQueue()
-    context = FakeRequestContext(metadata={"iac_code": {"cwd": str(tmp_path / "missing")}})
+    context = FakeRequestContext(metadata={"iac_code": {"cwd": str(missing)}})
+
+    await executor.execute(context, queue)
+
+    assert missing.is_dir()
+    final_state = dump(queue.events[-1])["status"]["state"]
+    assert final_state != "TASK_STATE_FAILED"
+
+
+@pytest.mark.asyncio
+async def test_executor_rejects_workspace_path_pointing_at_file(tmp_path: Path) -> None:
+    file_path = tmp_path / "not-a-dir"
+    file_path.write_text("blocker")
+    store = A2ATaskStore(metrics=NoOpA2AMetrics())
+    executor = IacCodeA2AExecutor(task_store=store, model="qwen3.6-plus")
+    queue = FakeEventQueue()
+    context = FakeRequestContext(metadata={"iac_code": {"cwd": str(file_path)}})
 
     await executor.execute(context, queue)
 
@@ -436,6 +456,61 @@ async def run_streaming(self, prompt: str):
     assert sorted(prompts) == ["one", "two"]
 
 
+@pytest.mark.asyncio
+async def test_executor_resumes_messages_after_restart(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    from iac_code.a2a.persistence import A2APersistenceStore
+    from iac_code.agent.message import Message
+    from iac_code.services.session_storage import SessionStorage
+
+    config_dir = tmp_path / "config"
+    config_dir.mkdir()
+    monkeypatch.setenv("IAC_CODE_CONFIG_DIR", str(config_dir))
+
+    cwd = tmp_path / "ws"
+    cwd.mkdir()
+
+    seen_resume: list[object | None] = []
+
+    def fake_factory(options):
+        seen_resume.append(options.resume_messages)
+        return FakeRuntime(
+            agent_loop=FakeAgentLoop([TextDeltaEvent(text="ok")]),
+            session_id=options.session_id,
+        )
+
+    monkeypatch.setattr("iac_code.a2a.executor.create_agent_runtime", fake_factory)
+
+    persistence = A2APersistenceStore(tmp_path / "a2a")
+
+    store_one = A2ATaskStore(metrics=NoOpA2AMetrics(), persistence=persistence)
+    executor_one = IacCodeA2AExecutor(task_store=store_one, model="qwen3.6-plus")
+    ctx_one = FakeRequestContext(
+        task_id="task-1",
+        context_id="ctx-shared",
+        text="hi-1",
+        metadata={"iac_code": {"cwd": str(cwd)}},
+    )
+    await executor_one.execute(ctx_one, FakeEventQueue())
+    session_id = store_one._contexts["ctx-shared"].session_id
+
+    SessionStorage().append(str(cwd), session_id, Message(role="user", content="prior turn"))
+
+    store_two = A2ATaskStore(metrics=NoOpA2AMetrics(), persistence=persistence)
+    executor_two = IacCodeA2AExecutor(task_store=store_two, model="qwen3.6-plus")
+    ctx_two = FakeRequestContext(
+        task_id="task-2",
+        context_id="ctx-shared",
+        text="hi-2",
+        metadata={"iac_code": {"cwd": str(cwd)}},
+    )
+    await executor_two.execute(ctx_two, FakeEventQueue())
+
+    assert store_two._contexts["ctx-shared"].session_id == session_id
+    assert seen_resume[0] is None
+    assert seen_resume[1] is not None
+    assert any(getattr(m, "content", "") == "prior turn" for m in seen_resume[1])
+
+
 @pytest.mark.asyncio
 async def test_auth_error_is_sanitized(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
     def raise_auth_error(options):
diff --git a/tests/a2a/test_task_store.py b/tests/a2a/test_task_store.py
index fe45df8f..10d931a6 100644
--- a/tests/a2a/test_task_store.py
+++ b/tests/a2a/test_task_store.py
@@ -268,6 +268,38 @@ async def test_task_store_mirrors_task_and_context_to_persistence(tmp_path) -> N
     assert persistence.load_task("task-1").context_id == task.context_id
 
 
+@pytest.mark.asyncio
+async def test_get_or_create_context_restores_persisted_session_id(tmp_path) -> None:
+    from iac_code.a2a.persistence import A2APersistenceStore
+
+    persistence = A2APersistenceStore(tmp_path)
+    store_one = A2ATaskStore(metrics=NoOpA2AMetrics(), persistence=persistence)
+    original = await store_one.get_or_create_context(
+        context_id="ctx-1", cwd="/tmp", runtime_factory=lambda sid: f"rt-{sid}"
+    )
+
+    store_two = A2ATaskStore(metrics=NoOpA2AMetrics(), persistence=persistence)
+    restored = await store_two.get_or_create_context(
+        context_id="ctx-1", cwd="/tmp", runtime_factory=lambda sid: f"rt-{sid}"
+    )
+
+    assert restored.session_id == original.session_id
+    assert restored.runtime == f"rt-{original.session_id}"
+
+
+@pytest.mark.asyncio
+async def test_get_or_create_context_persisted_cwd_mismatch_raises(tmp_path) -> None:
+    from iac_code.a2a.persistence import A2APersistenceStore
+
+    persistence = A2APersistenceStore(tmp_path)
+    store_one = A2ATaskStore(metrics=NoOpA2AMetrics(), persistence=persistence)
+    await store_one.get_or_create_context(context_id="ctx-1", cwd="/tmp/one", runtime_factory=lambda sid: object())
+
+    store_two = A2ATaskStore(metrics=NoOpA2AMetrics(), persistence=persistence)
+    with pytest.raises(ValueError, match="different workspace"):
+        await store_two.get_or_create_context(context_id="ctx-1", cwd="/tmp/two", runtime_factory=lambda sid: object())
+
+
 @pytest.mark.asyncio
 async def test_task_store_persistence_failure_does_not_abort_task_creation() -> None:
     store = A2ATaskStore(metrics=NoOpA2AMetrics(), persistence=FailingPersistence())
diff --git a/tests/conftest.py b/tests/conftest.py
index 3f0ba2db..81cf0e98 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -37,6 +37,10 @@ def _isolate_iac_home(tmp_path_factory, monkeypatch):
 
     A separate tmp dir (not the test's own ``tmp_path``) is used so tests that
     treat ``tmp_path`` as "outside $HOME" still behave correctly.
+
+    Also unset IAC_CODE_CONFIG_DIR so a developer's local override cannot
+    leak into tests that rely on the ``Path.home() / ".iac-code"`` fallback.
     """
     fake_home = tmp_path_factory.mktemp("iac_home")
     monkeypatch.setenv("HOME", str(fake_home))
+    monkeypatch.delenv("IAC_CODE_CONFIG_DIR", raising=False)
diff --git a/tests/skills/test_discovery.py b/tests/skills/test_discovery.py
index a92325e7..9c6ca09c 100644
--- a/tests/skills/test_discovery.py
+++ b/tests/skills/test_discovery.py
@@ -198,3 +198,25 @@ def test_glob_pattern_matching(self):
         skill = self._make_skill("src-skill", ["src/**/*.py"])
         tracker.on_file_accessed("src/core/main.py", [skill])
         assert len(tracker.get_activated_skills()) == 1
+
+
+class TestUserGlobalSkillsRespectConfigDirEnv:
+    def test_user_global_skills_dir_respects_env(self, monkeypatch, tmp_path):
+        """User-global skills are loaded from IAC_CODE_CONFIG_DIR/skills."""
+        target = tmp_path / "alt-config"
+        monkeypatch.setenv("IAC_CODE_CONFIG_DIR", str(target))
+
+        skills_dir = target / "skills"
+        skills_dir.mkdir(parents=True)
+        (skills_dir / "alpha.md").write_text("---\ndescription: Alpha\n---\n")
+
+        project_cwd = tmp_path / "proj"
+        project_cwd.mkdir()
+
+        from iac_code.skills.discovery import discover_all_skills
+        from iac_code.types.skill_source import SkillSource
+
+        skills = discover_all_skills(str(project_cwd))
+        alpha = next((s for s in skills if s.name == "alpha"), None)
+        assert alpha is not None
+        assert alpha.source == SkillSource.USER
diff --git a/tests/test_config_dir_env.py b/tests/test_config_dir_env.py
new file mode 100644
index 00000000..acd56eca
--- /dev/null
+++ b/tests/test_config_dir_env.py
@@ -0,0 +1,174 @@
+"""Tests for IAC_CODE_CONFIG_DIR env-var override of get_config_dir()."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from unittest.mock import patch
+
+
+class TestResolveConfigDirFallback:
+    def test_unset_falls_back_to_home_dot_iac_code(self, monkeypatch, tmp_path):
+        monkeypatch.delenv("IAC_CODE_CONFIG_DIR", raising=False)
+        with patch("iac_code.config.Path.home", return_value=tmp_path):
+            from iac_code.config import get_config_dir
+
+            result = get_config_dir()
+            assert result == tmp_path / ".iac-code"
+            assert result.is_dir()
+
+    def test_empty_string_treated_as_unset(self, monkeypatch, tmp_path):
+        monkeypatch.setenv("IAC_CODE_CONFIG_DIR", "")
+        with patch("iac_code.config.Path.home", return_value=tmp_path):
+            from iac_code.config import get_config_dir
+
+            assert get_config_dir() == tmp_path / ".iac-code"
+
+    def test_whitespace_only_treated_as_unset(self, monkeypatch, tmp_path):
+        monkeypatch.setenv("IAC_CODE_CONFIG_DIR", "   \t\n")
+        with patch("iac_code.config.Path.home", return_value=tmp_path):
+            from iac_code.config import get_config_dir
+
+            assert get_config_dir() == tmp_path / ".iac-code"
+
+    def test_absolute_path_used_as_is(self, monkeypatch, tmp_path):
+        target = tmp_path / "custom-config"
+        monkeypatch.setenv("IAC_CODE_CONFIG_DIR", str(target))
+        from iac_code.config import get_config_dir
+
+        result = get_config_dir()
+        assert result == target.resolve()
+        assert result.is_dir()
+
+
+class TestResolveConfigDirExpansion:
+    def test_tilde_expansion(self, monkeypatch, tmp_path):
+        # Pretend $HOME is tmp_path so ~/work/iac resolves into our sandbox.
+        monkeypatch.setenv("HOME", str(tmp_path))
+        monkeypatch.setenv("IAC_CODE_CONFIG_DIR", "~/work/iac")
+        from iac_code.config import get_config_dir
+
+        result = get_config_dir()
+        assert result == (tmp_path / "work" / "iac").resolve()
+        assert result.is_dir()
+
+    def test_env_var_expansion(self, monkeypatch, tmp_path):
+        base = tmp_path / "base-from-var"
+        monkeypatch.setenv("MY_BASE", str(base))
+        monkeypatch.setenv("IAC_CODE_CONFIG_DIR", "$MY_BASE/iac")
+        from iac_code.config import get_config_dir
+
+        result = get_config_dir()
+        assert result == (base / "iac").resolve()
+        assert result.is_dir()
+
+    def test_relative_path_resolved_against_cwd(self, monkeypatch, tmp_path):
+        monkeypatch.chdir(tmp_path)
+        monkeypatch.setenv("IAC_CODE_CONFIG_DIR", "./rel-iac")
+        from iac_code.config import get_config_dir
+
+        result = get_config_dir()
+        assert result == (tmp_path / "rel-iac").resolve()
+        assert result.is_dir()
+
+    def test_creates_parent_dirs(self, monkeypatch, tmp_path):
+        target = tmp_path / "a" / "b" / "c"
+        monkeypatch.setenv("IAC_CODE_CONFIG_DIR", str(target))
+        from iac_code.config import get_config_dir
+
+        result = get_config_dir()
+        assert result == target.resolve()
+        assert result.is_dir()
+        assert (tmp_path / "a" / "b").is_dir()
+
+
+class TestResolveConfigDirEdgeCases:
+    def test_mkdir_failure_propagates(self, monkeypatch, tmp_path):
+        # Point at a path that we then make impossible to create by
+        # replacing Path.mkdir with a stub that raises.
+        target = tmp_path / "no-permission"
+        monkeypatch.setenv("IAC_CODE_CONFIG_DIR", str(target))
+
+        original_mkdir = Path.mkdir
+
+        def boom(self, *args, **kwargs):  # type: ignore[no-untyped-def]
+            if str(self).startswith(str(target)):
+                raise PermissionError("simulated")
+            return original_mkdir(self, *args, **kwargs)
+
+        monkeypatch.setattr(Path, "mkdir", boom)
+
+        import pytest
+
+        from iac_code.config import get_config_dir
+
+        with pytest.raises(PermissionError):
+            get_config_dir()
+
+    def test_env_changes_picked_up_immediately(self, monkeypatch, tmp_path):
+        first = tmp_path / "first"
+        second = tmp_path / "second"
+        monkeypatch.setenv("IAC_CODE_CONFIG_DIR", str(first))
+        from iac_code.config import get_config_dir
+
+        assert get_config_dir() == first.resolve()
+
+        monkeypatch.setenv("IAC_CODE_CONFIG_DIR", str(second))
+        assert get_config_dir() == second.resolve()
+
+
+class TestSubpathsFollowEnv:
+    def test_root_file_paths_follow_env(self, monkeypatch, tmp_path):
+        target = tmp_path / "custom"
+        monkeypatch.setenv("IAC_CODE_CONFIG_DIR", str(target))
+
+        from iac_code.config import (
+            get_cloud_credentials_path,
+            get_credentials_path,
+            get_history_path,
+            get_settings_path,
+        )
+
+        assert get_credentials_path() == target.resolve() / ".credentials.yml"
+        assert get_settings_path() == target.resolve() / "settings.yml"
+        assert get_cloud_credentials_path() == target.resolve() / ".cloud-credentials.yml"
+        assert get_history_path() == target.resolve() / ".input_history"
+
+    def test_projects_dir_follows_env(self, monkeypatch, tmp_path):
+        target = tmp_path / "custom"
+        monkeypatch.setenv("IAC_CODE_CONFIG_DIR", str(target))
+
+        from iac_code.utils.project_paths import get_projects_dir
+
+        assert get_projects_dir() == target.resolve() / "projects"
+
+    def test_image_cache_dir_follows_env(self, monkeypatch, tmp_path):
+        target = tmp_path / "custom"
+        monkeypatch.setenv("IAC_CODE_CONFIG_DIR", str(target))
+
+        from iac_code.utils.image.store import _get_base_dir
+
+        assert _get_base_dir() == target.resolve() / "image-cache"
+
+
+class TestUserSkillsFollowEnv:
+    def test_user_global_skills_loaded_from_env_dir(self, monkeypatch, tmp_path):
+        target = tmp_path / "custom-config"
+        monkeypatch.setenv("IAC_CODE_CONFIG_DIR", str(target))
+
+        # Place a skill under the configured user-global skills dir.
+        user_skills = target / "skills"
+        user_skills.mkdir(parents=True)
+        (user_skills / "my-skill.md").write_text("---\ndescription: Sample skill\n---\nBody.\n")
+
+        # Use a cwd with no project skills so the only USER skill found
+        # must come from <env>/skills/.
+        project_cwd = tmp_path / "empty-project"
+        project_cwd.mkdir()
+
+        from iac_code.skills.discovery import discover_all_skills
+        from iac_code.types.skill_source import SkillSource
+
+        skills = discover_all_skills(str(project_cwd))
+        names = {s.name: s for s in skills if s.source == SkillSource.USER}
+        assert "my-skill" in names
+        assert names["my-skill"].description == "Sample skill"
diff --git a/website/docs/configuration/environment-variables.md b/website/docs/configuration/environment-variables.md
index 24882d30..fe647ab0 100644
--- a/website/docs/configuration/environment-variables.md
+++ b/website/docs/configuration/environment-variables.md
@@ -51,6 +51,7 @@ See [Alibaba Cloud Credentials](./alibaba-cloud-credentials.md) for more details
 
 | Variable | Description |
 |---|---|
+| `IAC_CODE_CONFIG_DIR` | Override the runtime configuration directory (default `~/.iac-code/`); supports `~` and `$VAR` expansion. All persisted artifacts (credentials, settings, history, projects, image cache, skills, telemetry, etc.) follow it |
 | `IAC_CODE_ENV` | Deployment environment label (default: `production`) |
 | `IAC_CODE_TENANT_ID` | Tenant identifier for telemetry; auto-prefixed with `iac_tenant_` if not already |
 | `OTEL_EXPORTER_OTLP_ENDPOINT` | Standard OpenTelemetry endpoint; when set, enables OTLP export |
diff --git a/website/docs/configuration/runtime-configuration.md b/website/docs/configuration/runtime-configuration.md
index 71200977..5263ba3e 100644
--- a/website/docs/configuration/runtime-configuration.md
+++ b/website/docs/configuration/runtime-configuration.md
@@ -13,12 +13,14 @@ Configuration precedence:
 CLI arguments > environment variables > configuration files
 ```
 
-The runtime directory is:
+The runtime directory defaults to:
 
 ```text
 ~/.iac-code/
 ```
 
+You can relocate it by setting the `IAC_CODE_CONFIG_DIR` environment variable (supports `~` and `$VAR` expansion). When set, every persisted artifact — credentials, settings, history, `projects/`, `image-cache/`, `tool-results/`, `logs/`, `memory/`, `a2a/`, `telemetry/`, `skills/` — follows the new location.
+
 Common files:
 
 | File | Description |
diff --git a/website/i18n/de/docusaurus-plugin-content-docs/current/configuration/environment-variables.md b/website/i18n/de/docusaurus-plugin-content-docs/current/configuration/environment-variables.md
index 640e0744..a6f979a7 100644
--- a/website/i18n/de/docusaurus-plugin-content-docs/current/configuration/environment-variables.md
+++ b/website/i18n/de/docusaurus-plugin-content-docs/current/configuration/environment-variables.md
@@ -51,6 +51,7 @@ Siehe [Alibaba Cloud-Anmeldedaten](./alibaba-cloud-credentials.md) fuer weitere
 
 | Variable | Beschreibung |
 |---|---|
+| `IAC_CODE_CONFIG_DIR` | Ueberschreibt das Laufzeitkonfigurationsverzeichnis (Standard `~/.iac-code/`); unterstuetzt `~`- und `$VAR`-Erweiterung. Alle persistierten Artefakte (Anmeldedaten, Einstellungen, Verlauf, projects, image-cache, skills, telemetry usw.) folgen diesem Verzeichnis |
 | `IAC_CODE_ENV` | Bezeichnung der Bereitstellungsumgebung (Standard: `production`) |
 | `IAC_CODE_TENANT_ID` | Mandantenkennung fuer Telemetrie; wird automatisch mit `iac_tenant_` vorangestellt, wenn nicht bereits vorhanden |
 | `OTEL_EXPORTER_OTLP_ENDPOINT` | Standard-OpenTelemetry-Endpunkt; aktiviert den OTLP-Export, wenn gesetzt |
diff --git a/website/i18n/de/docusaurus-plugin-content-docs/current/configuration/runtime-configuration.md b/website/i18n/de/docusaurus-plugin-content-docs/current/configuration/runtime-configuration.md
index 8e4a870c..81000cdd 100644
--- a/website/i18n/de/docusaurus-plugin-content-docs/current/configuration/runtime-configuration.md
+++ b/website/i18n/de/docusaurus-plugin-content-docs/current/configuration/runtime-configuration.md
@@ -13,12 +13,14 @@ Konfigurationspriorität:
 CLI-Argumente > Umgebungsvariablen > Konfigurationsdateien
 ```
 
-Das Laufzeitverzeichnis ist:
+Das Laufzeitverzeichnis ist standardmäßig:
 
 ```text
 ~/.iac-code/
 ```
 
+Sie können es verlegen, indem Sie die Umgebungsvariable `IAC_CODE_CONFIG_DIR` setzen (unterstützt `~`- und `$VAR`-Erweiterung). Sobald gesetzt, folgen alle persistierten Artefakte — Anmeldedaten, Einstellungen, Verlauf, `projects/`, `image-cache/`, `tool-results/`, `logs/`, `memory/`, `a2a/`, `telemetry/`, `skills/` — dem neuen Speicherort.
+
 Häufige Dateien:
 
 | Datei | Beschreibung |
diff --git a/website/i18n/es/docusaurus-plugin-content-docs/current/configuration/environment-variables.md b/website/i18n/es/docusaurus-plugin-content-docs/current/configuration/environment-variables.md
index 6915cfa7..ad4dfcab 100644
--- a/website/i18n/es/docusaurus-plugin-content-docs/current/configuration/environment-variables.md
+++ b/website/i18n/es/docusaurus-plugin-content-docs/current/configuration/environment-variables.md
@@ -51,6 +51,7 @@ Consulta [Credenciales de Alibaba Cloud](./alibaba-cloud-credentials.md) para ma
 
 | Variable | Descripcion |
 |---|---|
+| `IAC_CODE_CONFIG_DIR` | Sobreescribe el directorio de configuracion en tiempo de ejecucion (predeterminado `~/.iac-code/`); admite expansion de `~` y `$VAR`. Todos los artefactos persistidos (credenciales, ajustes, historial, projects, image-cache, skills, telemetry, etc.) siguen este directorio |
 | `IAC_CODE_ENV` | Etiqueta del entorno de despliegue (predeterminado: `production`) |
 | `IAC_CODE_TENANT_ID` | Identificador de tenant para telemetria; se le agrega automaticamente el prefijo `iac_tenant_` si no lo tiene |
 | `OTEL_EXPORTER_OTLP_ENDPOINT` | Endpoint estandar de OpenTelemetry; cuando se establece, habilita la exportacion OTLP |
diff --git a/website/i18n/es/docusaurus-plugin-content-docs/current/configuration/runtime-configuration.md b/website/i18n/es/docusaurus-plugin-content-docs/current/configuration/runtime-configuration.md
index 6a1197dd..0a3525cb 100644
--- a/website/i18n/es/docusaurus-plugin-content-docs/current/configuration/runtime-configuration.md
+++ b/website/i18n/es/docusaurus-plugin-content-docs/current/configuration/runtime-configuration.md
@@ -13,12 +13,14 @@ Precedencia de configuración:
 Argumentos CLI > variables de entorno > archivos de configuración
 ```
 
-El directorio de tiempo de ejecución es:
+El directorio de tiempo de ejecución por defecto es:
 
 ```text
 ~/.iac-code/
 ```
 
+Puede reubicarlo estableciendo la variable de entorno `IAC_CODE_CONFIG_DIR` (admite expansión de `~` y `$VAR`). Cuando se establece, todos los artefactos persistidos — credenciales, ajustes, historial, `projects/`, `image-cache/`, `tool-results/`, `logs/`, `memory/`, `a2a/`, `telemetry/`, `skills/` — siguen la nueva ubicación.
+
 Archivos comunes:
 
 | Archivo | Descripción |
diff --git a/website/i18n/fr/docusaurus-plugin-content-docs/current/configuration/environment-variables.md b/website/i18n/fr/docusaurus-plugin-content-docs/current/configuration/environment-variables.md
index 24487dab..1b0b27fc 100644
--- a/website/i18n/fr/docusaurus-plugin-content-docs/current/configuration/environment-variables.md
+++ b/website/i18n/fr/docusaurus-plugin-content-docs/current/configuration/environment-variables.md
@@ -51,6 +51,7 @@ Consultez [Identifiants Alibaba Cloud](./alibaba-cloud-credentials.md) pour plus
 
 | Variable | Description |
 |---|---|
+| `IAC_CODE_CONFIG_DIR` | Remplace le répertoire de configuration à l'exécution (par défaut `~/.iac-code/`) ; prend en charge l'expansion de `~` et `$VAR`. Tous les artefacts persistés (identifiants, paramètres, historique, projects, image-cache, skills, telemetry, etc.) suivent ce répertoire |
 | `IAC_CODE_ENV` | Label d'environnement de déploiement (par défaut : `production`) |
 | `IAC_CODE_TENANT_ID` | Identifiant de locataire pour la télémétrie ; préfixé automatiquement avec `iac_tenant_` si ce n'est pas déjà le cas |
 | `OTEL_EXPORTER_OTLP_ENDPOINT` | Point de terminaison OpenTelemetry standard ; lorsqu'il est défini, active l'export OTLP |
diff --git a/website/i18n/fr/docusaurus-plugin-content-docs/current/configuration/runtime-configuration.md b/website/i18n/fr/docusaurus-plugin-content-docs/current/configuration/runtime-configuration.md
index feba2abe..d86bcfc2 100644
--- a/website/i18n/fr/docusaurus-plugin-content-docs/current/configuration/runtime-configuration.md
+++ b/website/i18n/fr/docusaurus-plugin-content-docs/current/configuration/runtime-configuration.md
@@ -13,12 +13,14 @@ Priorité de configuration :
 Arguments CLI > variables d'environnement > fichiers de configuration
 ```
 
-Le répertoire d'exécution est :
+Le répertoire d'exécution par défaut est :
 
 ```text
 ~/.iac-code/
 ```
 
+Vous pouvez le déplacer en définissant la variable d'environnement `IAC_CODE_CONFIG_DIR` (prend en charge l'expansion de `~` et `$VAR`). Une fois définie, tous les artefacts persistés — identifiants, paramètres, historique, `projects/`, `image-cache/`, `tool-results/`, `logs/`, `memory/`, `a2a/`, `telemetry/`, `skills/` — suivent le nouvel emplacement.
+
 Fichiers courants :
 
 | Fichier | Description |
diff --git a/website/i18n/ja/docusaurus-plugin-content-docs/current/configuration/environment-variables.md b/website/i18n/ja/docusaurus-plugin-content-docs/current/configuration/environment-variables.md
index a18af9cc..9dd09333 100644
--- a/website/i18n/ja/docusaurus-plugin-content-docs/current/configuration/environment-variables.md
+++ b/website/i18n/ja/docusaurus-plugin-content-docs/current/configuration/environment-variables.md
@@ -51,6 +51,7 @@ CLI 引数 > 環境変数 > 設定ファイル
 
 | 変数 | 説明 |
 |---|---|
+| `IAC_CODE_CONFIG_DIR` | ランタイム設定ディレクトリを上書き（デフォルト `~/.iac-code/`）。`~` と `$VAR` の展開をサポート。永続化されるすべての成果物（認証情報、設定、履歴、projects、image-cache、skills、telemetry など）はこのディレクトリに従います |
 | `IAC_CODE_ENV` | デプロイ環境ラベル（デフォルト：`production`） |
 | `IAC_CODE_TENANT_ID` | テレメトリ用テナント識別子。`iac_tenant_` プレフィックスが付いていない場合は自動的に付加されます |
 | `OTEL_EXPORTER_OTLP_ENDPOINT` | 標準 OpenTelemetry エンドポイント。設定すると OTLP エクスポートが有効になります |
diff --git a/website/i18n/ja/docusaurus-plugin-content-docs/current/configuration/runtime-configuration.md b/website/i18n/ja/docusaurus-plugin-content-docs/current/configuration/runtime-configuration.md
index 8f0e2bf0..14c2d642 100644
--- a/website/i18n/ja/docusaurus-plugin-content-docs/current/configuration/runtime-configuration.md
+++ b/website/i18n/ja/docusaurus-plugin-content-docs/current/configuration/runtime-configuration.md
@@ -13,12 +13,14 @@ IaC Code は CLI 引数、環境変数、およびランタイム設定ディレ
 CLI 引数 > 環境変数 > 設定ファイル
 ```
 
-ランタイムディレクトリ：
+ランタイムディレクトリは既定で以下です：
 
 ```text
 ~/.iac-code/
 ```
 
+`IAC_CODE_CONFIG_DIR` 環境変数を設定すると、ディレクトリを変更できます（`~` と `$VAR` の展開をサポート）。設定すると、永続化されるすべての成果物 — 認証情報、設定、履歴、`projects/`、`image-cache/`、`tool-results/`、`logs/`、`memory/`、`a2a/`、`telemetry/`、`skills/` — が新しい場所に追従します。
+
 主要ファイル：
 
 | ファイル | 説明 |
diff --git a/website/i18n/pt/docusaurus-plugin-content-docs/current/configuration/environment-variables.md b/website/i18n/pt/docusaurus-plugin-content-docs/current/configuration/environment-variables.md
index 87a0b057..4595ae07 100644
--- a/website/i18n/pt/docusaurus-plugin-content-docs/current/configuration/environment-variables.md
+++ b/website/i18n/pt/docusaurus-plugin-content-docs/current/configuration/environment-variables.md
@@ -51,6 +51,7 @@ Consulte [Credenciais da Alibaba Cloud](./alibaba-cloud-credentials.md) para mai
 
 | Variavel | Descricao |
 |---|---|
+| `IAC_CODE_CONFIG_DIR` | Substitui o diretorio de configuracao em tempo de execucao (padrao `~/.iac-code/`); suporta expansao de `~` e `$VAR`. Todos os artefatos persistidos (credenciais, configuracoes, historico, projects, image-cache, skills, telemetry, etc.) seguem este diretorio |
 | `IAC_CODE_ENV` | Rotulo do ambiente de implantacao (padrao: `production`) |
 | `IAC_CODE_TENANT_ID` | Identificador de tenant para telemetria; prefixado automaticamente com `iac_tenant_` se ainda nao estiver |
 | `OTEL_EXPORTER_OTLP_ENDPOINT` | Endpoint padrao do OpenTelemetry; quando definido, habilita a exportacao OTLP |
diff --git a/website/i18n/pt/docusaurus-plugin-content-docs/current/configuration/runtime-configuration.md b/website/i18n/pt/docusaurus-plugin-content-docs/current/configuration/runtime-configuration.md
index d837fa31..8e68c99c 100644
--- a/website/i18n/pt/docusaurus-plugin-content-docs/current/configuration/runtime-configuration.md
+++ b/website/i18n/pt/docusaurus-plugin-content-docs/current/configuration/runtime-configuration.md
@@ -13,12 +13,14 @@ Precedência de configuração:
 Argumentos CLI > variáveis de ambiente > arquivos de configuração
 ```
 
-O diretório de tempo de execução é:
+O diretório de tempo de execução padrão é:
 
 ```text
 ~/.iac-code/
 ```
 
+Você pode realocá-lo definindo a variável de ambiente `IAC_CODE_CONFIG_DIR` (suporta expansão de `~` e `$VAR`). Quando definida, todos os artefatos persistidos — credenciais, configurações, histórico, `projects/`, `image-cache/`, `tool-results/`, `logs/`, `memory/`, `a2a/`, `telemetry/`, `skills/` — seguem o novo local.
+
 Arquivos comuns:
 
 | Arquivo | Descrição |
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/configuration/environment-variables.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/configuration/environment-variables.md
index d7bcd54e..9652d1d9 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/configuration/environment-variables.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/configuration/environment-variables.md
@@ -51,6 +51,7 @@ CLI 参数 > 环境变量 > 配置文件
 
 | 变量 | 说明 |
 |---|---|
+| `IAC_CODE_CONFIG_DIR` | 覆盖运行时配置目录（默认 `~/.iac-code/`）；支持 `~` 和 `$VAR` 展开。所有持久化产物（凭证、设置、历史、projects、image-cache、skills、telemetry 等）均会跟随该目录 |
 | `IAC_CODE_ENV` | 部署环境标签（默认：`production`） |
 | `IAC_CODE_TENANT_ID` | 遥测租户标识；如未以 `iac_tenant_` 开头则自动添加前缀 |
 | `OTEL_EXPORTER_OTLP_ENDPOINT` | 标准 OpenTelemetry 端点；设置后启用 OTLP 导出 |
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/configuration/runtime-configuration.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/configuration/runtime-configuration.md
index 605774d2..571f398c 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/configuration/runtime-configuration.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/configuration/runtime-configuration.md
@@ -13,12 +13,14 @@ IaC Code 会从 CLI 参数、环境变量以及运行时配置目录中的文件
 CLI 参数 > 环境变量 > 配置文件
 ```
 
-运行时目录为：
+运行时目录默认为：
 
 ```text
 ~/.iac-code/
 ```
 
+可通过设置 `IAC_CODE_CONFIG_DIR` 环境变量更改该目录（支持 `~` 和 `$VAR` 展开）。设置后，所有持久化产物——凭证、设置、历史、`projects/`、`image-cache/`、`tool-results/`、`logs/`、`memory/`、`a2a/`、`telemetry/`、`skills/`——都会跟随到新位置。
+
 常见文件：
 
 | 文件 | 说明 |