feat(core): single-source data_dir/repos_dir via castle.yaml

The `castle` CLI and the `castle-api` service are two independent in-process
drivers of `castle_core`. Each resolved DATA_DIR/REPOS_DIR at import time from
its own process env (default /data/castle), persisted nowhere — so they silently
diverged, and `apply`/dashboard-apply crashed on a non-existent /data.

Make the loaded CastleConfig the single source of truth:
- Resolve data_dir/repos_dir only in load_config (env > castle.yaml > default),
  anchored to the config root; drop the DATA_DIR/REPOS_DIR module globals and the
  import-time file read entirely — no global twin that can disagree with the file.
- Thread config.data_dir/repos_dir through ensure_dirs, _env_context, tls_dir_for
  (now unified — deploy no longer inlines the tls path), and create/add/clone.
- ensure_dirs raises an actionable CastleDirError instead of a bare PermissionError;
  the api surfaces it as 422.
- doctor: "data dir writable" check + WARN when CASTLE_DATA_DIR/REPOS_DIR env
  overrides the file (the one remaining cross-process divergence vector).
- install.sh persists data_dir/repos_dir into castle.yaml (idempotent, non-default).
- Docs: registry.md globals + AGENTS.md roots.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

cli/tests/test_create.py

@@ -18,9 +18,9 @@ class TestCreateCommand:
         with (
             patch("castle_cli.commands.create.load_config") as mock_load,
             patch("castle_cli.commands.create.save_config") as mock_save,
-            patch("castle_cli.commands.create.REPOS_DIR", repos),
         ):
             config = load_config(castle_root)
+            config.repos_dir = repos
             mock_load.return_value = config
 
             from castle_cli.commands.create import run_create
@@ -57,9 +57,9 @@ class TestCreateCommand:
         with (
             patch("castle_cli.commands.create.load_config") as mock_load,
             patch("castle_cli.commands.create.save_config"),
-            patch("castle_cli.commands.create.REPOS_DIR", repos),
         ):
             config = load_config(castle_root)
+            config.repos_dir = repos
             mock_load.return_value = config
 
             from castle_cli.commands.create import run_create
@@ -84,9 +84,9 @@ class TestCreateCommand:
         with (
             patch("castle_cli.commands.create.load_config") as mock_load,
             patch("castle_cli.commands.create.save_config"),
-            patch("castle_cli.commands.create.REPOS_DIR", repos),
         ):
             config = load_config(castle_root)
+            config.repos_dir = repos
             mock_load.return_value = config
 
             from castle_cli.commands.create import run_create
@@ -138,9 +138,9 @@ class TestCreateCommand:
         with (
             patch("castle_cli.commands.create.load_config") as mock_load,
             patch("castle_cli.commands.create.save_config"),
-            patch("castle_cli.commands.create.REPOS_DIR", tmp_path / "repos"),
         ):
             config = load_config(castle_root)
+            config.repos_dir = tmp_path / "repos"
             mock_load.return_value = config
 
             from castle_cli.commands.create import run_create

cli/tests/test_doctor.py

@@ -6,7 +6,8 @@ from argparse import Namespace
 from pathlib import Path
 from unittest.mock import patch
 
-from castle_cli.commands.doctor import run_doctor
+import pytest
+from castle_cli.commands.doctor import FAIL, OK, WARN, _check_configuration, run_doctor
 
 
 class TestDoctor:
@@ -37,3 +38,50 @@ class TestDoctor:
         out = capsys.readouterr().out  # type: ignore[attr-defined]
         assert "failed to load" in out
         assert "bad yaml" in out
+
+
+class TestDataDirChecks:
+    """The drift-prevention checks: data_dir must be writable, and a CASTLE_DATA_DIR env
+    override (the one way the CLI and api can still diverge) must be surfaced."""
+
+    def _config(self, castle_root: Path):
+        from castle_cli.config import load_config
+
+        return load_config(castle_root)
+
+    def test_writable_dir_ok_no_warn(
+        self, castle_root: Path, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        monkeypatch.delenv("CASTLE_DATA_DIR", raising=False)
+        monkeypatch.delenv("CASTLE_REPOS_DIR", raising=False)
+        cfg = self._config(castle_root)
+        cfg.data_dir = tmp_path  # exists + writable
+        checks = _check_configuration(cfg)
+        by_label = {c.label: c for c in checks}
+        assert by_label["data dir writable"].status == OK
+        assert not any("overrides castle.yaml" in c.label for c in checks)
+
+    def test_missing_dir_fails_with_hint(
+        self, castle_root: Path, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        monkeypatch.delenv("CASTLE_DATA_DIR", raising=False)
+        cfg = self._config(castle_root)
+        missing = tmp_path / "nope"
+        cfg.data_dir = missing
+        fail = next(
+            c for c in _check_configuration(cfg) if "data dir" in c.label and c.status == FAIL
+        )
+        assert str(missing) in fail.detail
+        assert fail.hint  # offers a concrete fix
+
+    def test_env_override_warns(
+        self, castle_root: Path, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """A CASTLE_DATA_DIR env var overrides the single-source-of-truth file — the
+        exact CLI/api divergence we fixed. Doctor must WARN."""
+        monkeypatch.setenv("CASTLE_DATA_DIR", str(tmp_path))
+        cfg = self._config(castle_root)
+        cfg.data_dir = tmp_path
+        warn = next(c for c in _check_configuration(cfg) if "overrides castle.yaml" in c.label)
+        assert warn.status == WARN
+        assert "CASTLE_DATA_DIR" in warn.detail