From a25754c653ed1a46723554c21ea45f6a382684ca Mon Sep 17 00:00:00 2001
From: Yev Meyer <ymeyer@nvidia.com>
Date: Mon, 2 Nov 2026 16:46:45 -0500
Subject: [PATCH 1/7] fix(engine): read prompts.yaml from the folder a probe's
 banks resolve to

load_prompt_file reads a probe's prompts.yaml from the folder probe_assets_dir resolves for it, as the probe's bank loaders do: the first root on the asset search path that holds the probe, or the assets_root its class declares. A root on USERSIM_ASSET_PATH that holds other probes' banks does not hide a probe's prompts, and a probe that declares assets_root has its prompts.yaml read from there.

A test covers each case.

Signed-off-by: Yev Meyer <ymeyer@nvidia.com>
---
 architecture/assets.md                      |  3 ++-
 docs/engine/README.md                       |  2 +-
 src/usersim/engine/core/prompt_loader.py    | 24 +++++++++++++--------
 tests/engine/core/test_prompt_resolution.py | 22 +++++++++++++++++--
 4 files changed, 38 insertions(+), 13 deletions(-)

diff --git a/architecture/assets.md b/architecture/assets.md
index 8986f98c..852969c4 100644
--- a/architecture/assets.md
+++ b/architecture/assets.md
@@ -31,7 +31,8 @@ set. Registration refuses a relative root. That root is searched for that
 probe only, after the first three entries and before the packaged directory,
 so a deliberate override wins over it. The built-in probes declare none. A
 probe's bank loader reads under its class's `assets_dir()`, the folder this
-search finds for the probe.
+search finds for the probe, and its `prompts.yaml` is read from that folder
+too.
 
 An explicit `--assets-dir` is **not** part of the search. It pins resolution
 to exactly that directory, for every probe in the run, including one that
diff --git a/docs/engine/README.md b/docs/engine/README.md
index aae70237..91046df8 100644
--- a/docs/engine/README.md
+++ b/docs/engine/README.md
@@ -528,7 +528,7 @@ what each one carries:
 | `core/persona.py` | Persona formatting for prompts (deterministic shuffle) |
 | `core/locale.py` | Locale → language + expected-script-ranges mapping (single source of truth for shipped locales) |
 | `core/localized.py` | `LocalizedText` wrapper for asset-bank fields with per-locale renderings (`for_locale(locale)` lookup with `en_US` fallback) |
-| `core/prompt_loader.py` | Reads per-probe prompt packs from `assets/<probe>/prompts.yaml` |
+| `core/prompt_loader.py` | Reads a probe's `prompts.yaml` from the folder its banks resolve to |
 | `core/messages.py` | Message, tool, theme formatting |
 | `core/preview.py` | Rich-based preview utilities for inspecting generated conversations |
 
diff --git a/src/usersim/engine/core/prompt_loader.py b/src/usersim/engine/core/prompt_loader.py
index 11de289b..ca1e3e35 100644
--- a/src/usersim/engine/core/prompt_loader.py
+++ b/src/usersim/engine/core/prompt_loader.py
@@ -4,15 +4,17 @@
 """YAML-based prompt template loader.
 
 Loads prompt templates from per-probe YAML files at
-``assets/<probe>/prompts.yaml``, falling back to the compiled-in
+``<asset root>/<probe>/prompts.yaml``, falling back to the compiled-in
 Python defaults if YAML files are not found. This allows prompt
 iteration and A/B testing without code changes.
 
-Per-probe asset layout: each probe owns its own folder under
-``assets/`` and stores its prompt templates as ``prompts.yaml``
-inside that folder, alongside its other assets (e.g.
-``assets/tool_calling/prompts.yaml`` lives next to
-``assets/tool_calling/toolsets_seed.parquet``).
+Per-probe asset layout: each probe owns a ``<probe>/`` folder under an
+asset root and stores its prompt templates as ``prompts.yaml`` inside
+that folder, alongside its other assets (e.g.
+``tool_calling/prompts.yaml`` lives next to
+``tool_calling/toolsets_seed.parquet``). The file is read from the
+folder :func:`~usersim.engine.core._assets.probe_assets_dir` resolves,
+the one the probe's banks are read from.
 """
 
 from __future__ import annotations
@@ -46,15 +48,19 @@ def _load_prompt_file_at(probe: str, assets_root: str) -> dict[str, Any]:
 
 
 def load_prompt_file(probe: str) -> dict[str, Any]:
-    """Load a probe's ``prompts.yaml`` from the active asset root.
+    """Load a probe's ``prompts.yaml`` from the folder its banks resolve to.
+
+    That is the first root on the asset search path holding ``probe``, or
+    the ``assets_root`` its class declares, so a root that holds other
+    probes' assets does not hide this probe's prompts.
 
     Returns an empty dict if the file doesn't exist or PyYAML is not
     available — callers should always pass a sensible compiled-in
     default to :func:`get_prompt` to cover that path.
     """
-    from usersim.engine.core._assets import default_assets_dir
+    from usersim.engine.core._assets import probe_assets_dir
 
-    return _load_prompt_file_at(probe, str(default_assets_dir()))
+    return _load_prompt_file_at(probe, str(probe_assets_dir(probe).parent))
 
 
 def get_prompt(probe: str, key: str, default: str = "") -> str:
diff --git a/tests/engine/core/test_prompt_resolution.py b/tests/engine/core/test_prompt_resolution.py
index 68c52ad8..317d0025 100644
--- a/tests/engine/core/test_prompt_resolution.py
+++ b/tests/engine/core/test_prompt_resolution.py
@@ -25,8 +25,8 @@
 import pytest
 import yaml
 
-from usersim.engine.core._assets import packaged_assets_dir, set_runtime_assets_dir
-from usersim.engine.core.prompt_loader import render_prompt
+from usersim.engine.core._assets import packaged_assets_dir, probe_assets_dir, set_runtime_assets_dir
+from usersim.engine.core.prompt_loader import get_prompt, load_prompt_file, render_prompt
 
 #: The theme-driven probes, mapped to the name each one gives the
 #: import-time constant behind ``user_agent_system_prompt()``. Spelled out
@@ -155,6 +155,24 @@ def test_missing_key_falls_back_to_the_compiled_default(self, tmp_path):
         assert oe.trajectory_rubric() == "R"
 
 
+class TestPromptFileIsReadWhereTheBanksAre:
+    """A probe's ``prompts.yaml`` comes from the folder its banks resolve to."""
+
+    def test_a_root_holding_other_probes_does_not_hide_the_shipped_prompts(self, tmp_path):
+        set_runtime_assets_dir(_assets_with_prompt(tmp_path, "tool_calling", user_agent_system_prompt="OTHER"))
+
+        shipped = yaml.safe_load((probe_assets_dir("general_open_ended") / "prompts.yaml").read_text())
+        assert shipped
+        assert load_prompt_file("general_open_ended") == shipped
+
+    def test_a_declared_root_supplies_its_probes_prompts(self, register_test_probe, tmp_path):
+        register_test_probe(
+            "ext_probe", assets_root=_assets_with_prompt(tmp_path, "ext_probe", user_agent_system_prompt="EXT")
+        )
+
+        assert get_prompt("ext_probe", "user_agent_system_prompt") == "EXT"
+
+
 # ---------------------------------------------------------------------------
 # Per-row wiring
 # ---------------------------------------------------------------------------

From 711019c282c85718d31a3c7b35eaa67ece935a23 Mon Sep 17 00:00:00 2001
From: Yev Meyer <ymeyer@nvidia.com>
Date: Mon, 2 Nov 2026 16:47:02 -0500
Subject: [PATCH 2/7] build: ship the banks a probe keeps in its own folder

Package data includes the files under probes/<label>/assets/ in usersim.engine, and check_dist requires a bank's Markdown there to ship, as it does under engine/assets/.

Signed-off-by: Yev Meyer <ymeyer@nvidia.com>
---
 pyproject.toml           |  5 +++++
 scripts/check_dist.py    | 14 +++++++++++++-
 tests/test_check_dist.py |  8 ++++++--
 3 files changed, 24 insertions(+), 3 deletions(-)

diff --git a/pyproject.toml b/pyproject.toml
index b6309a32..e9365c8b 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -173,6 +173,11 @@ include = ["usersim*"]
     "assets/**/*.json",
     "assets/**/*.parquet",
     "assets/**/*.md",
+    # The banks a probe keeps in its own folder, under probes/<label>/assets/.
+    "probes/*/assets/**/*.yml",
+    "probes/*/assets/**/*.json",
+    "probes/*/assets/**/*.parquet",
+    "probes/*/assets/**/*.md",
     "**/*.yaml",
 ]
 "usersim.asset_gen" = [
diff --git a/scripts/check_dist.py b/scripts/check_dist.py
index fe4266b6..dd1abe5e 100644
--- a/scripts/check_dist.py
+++ b/scripts/check_dist.py
@@ -33,6 +33,18 @@
 REPO_ROOT = Path(__file__).resolve().parents[1]
 
 
+def in_a_bank(path: str) -> bool:
+    """Whether a package file is in an asset bank.
+
+    Banks live under ``usersim/engine/assets/``, or in the ``assets/`` folder
+    of a probe kept in its own folder, ``usersim/engine/probes/<label>/assets/``.
+    """
+    parts = path.split("/")
+    return path.startswith("usersim/engine/assets/") or (
+        parts[:3] == ["usersim", "engine", "probes"] and parts[4:5] == ["assets"]
+    )
+
+
 def ships(path: str) -> bool:
     """Whether a package file belongs in the wheel.
 
@@ -41,7 +53,7 @@ def ships(path: str) -> bool:
     """
     if path.endswith(".ipynb"):
         return False
-    return not path.endswith(".md") or path.startswith("usersim/engine/assets/")
+    return not path.endswith(".md") or in_a_bank(path)
 
 
 def tracked_package_files(root: Path = REPO_ROOT) -> list[str]:
diff --git a/tests/test_check_dist.py b/tests/test_check_dist.py
index 95a0fd5f..cb72d69d 100644
--- a/tests/test_check_dist.py
+++ b/tests/test_check_dist.py
@@ -78,8 +78,12 @@ def test_a_package_file_missing_from_the_wheel_is_reported(tmp_path: Path) -> No
     assert len(problems) == 1 and "lacks 1 package file" in problems[0] and spec in problems[0]
 
 
-def test_a_bank_schema_must_ship(tmp_path: Path) -> None:
-    schema = "usersim/engine/assets/probe/SCHEMA.md"
+@pytest.mark.parametrize(
+    "schema",
+    ["usersim/engine/assets/probe/SCHEMA.md", "usersim/engine/probes/probe/assets/probe/SCHEMA.md"],
+    ids=["shared-assets-folder", "probe-folder"],
+)
+def test_a_bank_schema_must_ship(tmp_path: Path, schema: str) -> None:
     problems = check_dist.check_archives(*_pair(tmp_path), package_files=[*_PACKAGE, schema])
     assert len(problems) == 1 and schema in problems[0]
 

From ea5c1cc247127730180b6697ab2d80ae1e51cffc Mon Sep 17 00:00:00 2001
From: Yev Meyer <ymeyer@nvidia.com>
Date: Mon, 2 Nov 2026 16:47:14 -0500
Subject: [PATCH 3/7] feat(engine): reach a built-in's own banks from the
 pinned packaged root

A pinned asset root is searched alone. Pinning the packaged directory, as --assets-dir can and as rows stored by a run that named no folder and set no override do, pins the assets that ship with User Sim. For a probe that directory does not hold, probe_assets_dir returns the folder under the root the probe's class declares when that root is inside the package. An extension's root is outside it, so the pin stays strict for an extension.

Signed-off-by: Yev Meyer <ymeyer@nvidia.com>
---
 architecture/assets.md                     |  4 +++
 src/usersim/engine/core/_assets.py         | 27 +++++++++++++--
 tests/engine/core/test_assets_discovery.py | 40 ++++++++++++++++++++++
 3 files changed, 69 insertions(+), 2 deletions(-)

diff --git a/architecture/assets.md b/architecture/assets.md
index 852969c4..2bc73fcf 100644
--- a/architecture/assets.md
+++ b/architecture/assets.md
@@ -38,6 +38,10 @@ An explicit `--assets-dir` is **not** part of the search. It pins resolution
 to exactly that directory, for every probe in the run, including one that
 declares `assets_root`, because a user who named a location should be told
 when the assets are not there rather than quietly served another copy.
+Pinning the packaged directory pins the assets that ship with User Sim, so it
+also reaches a built-in probe whose banks are in its own folder.
+`simulate --inputs` pins the folder its rows were stored with: the packaged
+directory, for rows stored by a run that named no folder and set no override.
 
 There is no fallback to the working directory. Resolving against wherever the
 process happened to start makes a broken install look healthy from a source
diff --git a/src/usersim/engine/core/_assets.py b/src/usersim/engine/core/_assets.py
index 225297a3..c36bb2af 100644
--- a/src/usersim/engine/core/_assets.py
+++ b/src/usersim/engine/core/_assets.py
@@ -29,7 +29,9 @@
 It pins resolution to exactly that directory, for every probe, including
 one whose class declares a root. A user who named a location wants to be
 told when the assets are not there, rather than to be quietly served
-another copy instead.
+another copy instead. The packaged directory stands for the assets that
+ship with User Sim, so pinning it also reaches a built-in probe whose
+banks are in its own folder.
 
 There is deliberately no CWD fallback: resolving against whatever
 directory the process happened to start in makes a broken install look
@@ -180,11 +182,13 @@ def probe_assets_dir(
             the search path. This is what ``--assets-dir`` becomes: a
             user who named a location is told when the assets are not
             there rather than quietly served the packaged copies.
+            Pinning the packaged directory reaches every bank that ships
+            with User Sim, a built-in kept in its own folder included.
             When ``None``, :func:`probe_asset_roots` is walked and the
             first root holding ``probe`` wins.
     """
     if assets_root is not None:
-        return Path(assets_root) / probe
+        return _pinned_probe_dir(probe, Path(assets_root))
 
     roots = probe_asset_roots(probe)
     for root in roots:
@@ -195,3 +199,22 @@ def probe_assets_dir(
     # been: the root the probe declares, else the highest-priority root.
     declared = declared_assets_roots().get(probe)
     return (declared if declared is not None else roots[0]) / probe
+
+
+def _pinned_probe_dir(probe: str, root: Path) -> Path:
+    """``probe``'s folder under the pinned ``root``.
+
+    The packaged directory stands for the assets that ship with User Sim, so
+    for a probe it does not hold, pinning it reaches the root the probe's class
+    declares when that root is inside this package. An extension's root is
+    outside it, so the pin stays strict for an extension.
+    """
+    folder = root / probe
+    packaged = packaged_assets_dir().resolve()
+    if folder.is_dir() or root.resolve() != packaged:
+        return folder
+    declared = declared_assets_roots().get(probe)
+    # ``packaged`` is ``usersim/engine/assets/``, so ``parents[1]`` is the package.
+    if declared is not None and declared.resolve().is_relative_to(packaged.parents[1]):
+        return declared / probe
+    return folder
diff --git a/tests/engine/core/test_assets_discovery.py b/tests/engine/core/test_assets_discovery.py
index 14e04200..45cf4f6b 100644
--- a/tests/engine/core/test_assets_discovery.py
+++ b/tests/engine/core/test_assets_discovery.py
@@ -270,3 +270,43 @@ def test_a_deliberate_override_reaches_the_probe(self, register_test_probe, monk
         probe = register_test_probe("ext_probe", assets_root=declared)
 
         assert probe.assets_dir() == override / "ext_probe"
+
+
+class TestPinnedPackagedRoot:
+    """Pinning the packaged directory pins the assets that ship with User Sim."""
+
+    @staticmethod
+    def _package(monkeypatch, tmp_path: Path) -> Path:
+        """A stand-in ``usersim`` package whose packaged banks are at ``engine/assets/``."""
+        import usersim.engine.core._assets as assets
+
+        package = tmp_path / "usersim"
+        (package / "engine" / "assets").mkdir(parents=True)
+        monkeypatch.setattr(assets, "packaged_assets_dir", lambda: package / "engine" / "assets")
+        return package
+
+    def test_it_reaches_a_probe_whose_banks_are_in_its_own_folder_in_the_package(
+        self, register_test_probe, monkeypatch, tmp_path
+    ) -> None:
+        package = self._package(monkeypatch, tmp_path)
+        own = package / "engine" / "probes" / "ext_probe" / "assets"
+        (own / "ext_probe").mkdir(parents=True)
+        register_test_probe("ext_probe", assets_root=own)
+
+        assert probe_assets_dir("ext_probe", assets_root=package / "engine" / "assets") == own / "ext_probe"
+
+    def test_it_stays_strict_for_a_root_outside_the_package(self, register_test_probe, monkeypatch, tmp_path) -> None:
+        package = self._package(monkeypatch, tmp_path)
+        (tmp_path / "extension" / "ext_probe").mkdir(parents=True)
+        register_test_probe("ext_probe", assets_root=tmp_path / "extension")
+
+        pinned = package / "engine" / "assets"
+        assert probe_assets_dir("ext_probe", assets_root=pinned) == pinned / "ext_probe"
+
+    def test_any_other_pinned_root_stays_strict(self, register_test_probe, monkeypatch, tmp_path) -> None:
+        package = self._package(monkeypatch, tmp_path)
+        own = package / "engine" / "probes" / "ext_probe" / "assets"
+        (own / "ext_probe").mkdir(parents=True)
+        register_test_probe("ext_probe", assets_root=own)
+
+        assert probe_assets_dir("ext_probe", assets_root=tmp_path / "mine") == tmp_path / "mine" / "ext_probe"

From 7846f72316df654a46b0ebf8a14a7a1611010057 Mon Sep 17 00:00:00 2001
From: Yev Meyer <ymeyer@nvidia.com>
Date: Mon, 2 Nov 2026 16:47:22 -0500
Subject: [PATCH 4/7] refactor(engine): keep general_educational in one folder

The probe module is probes/general_educational/probe.py and its banks are in probes/general_educational/assets/general_educational/, the folder the class names as its assets_root. Its label, prompts, seeds and stored columns are unchanged.

Tests that read its seeds or prompts from the packaged directory resolve them through the probe's folder, and the asset discovery tests accept a built-in whose banks are in its own folder inside the package and check that such a built-in names the assets folder beside its module.

Signed-off-by: Yev Meyer <ymeyer@nvidia.com>
---
 architecture/assets.md                        | 11 ++++----
 architecture/probes.md                        |  3 +-
 src/usersim/engine/core/_assets.py            |  8 ++++--
 src/usersim/engine/core/probes.py             | 14 +++++-----
 .../assets/general_educational/prompts.yaml   |  0
 .../subjects/base/subjects.json               |  0
 .../subjects/de_DE/subjects.json              |  0
 .../subjects/en_GB/subjects.json              |  0
 .../subjects/fr_FR/subjects.json              |  0
 .../subjects/hi_Deva_IN/subjects.json         |  0
 .../subjects/hi_Latn_IN/subjects.json         |  0
 .../subjects/ja_JP/subjects.json              |  0
 .../subjects/ko_KR/subjects.json              |  0
 .../subjects/pt_BR/subjects.json              |  0
 .../{generator.py => probe.py}                |  2 ++
 .../engine/probes/tool_calling/generator.py   |  2 +-
 tests/engine/core/test_assets_discovery.py    | 28 +++++++++++++++----
 tests/engine/core/test_multi_locale.py        | 26 ++++++++---------
 tests/engine/core/test_prompt_resolution.py   |  6 ++--
 tests/engine/core/test_provenance.py          |  2 +-
 20 files changed, 63 insertions(+), 39 deletions(-)
 rename src/usersim/engine/{ => probes/general_educational}/assets/general_educational/prompts.yaml (100%)
 rename src/usersim/engine/{ => probes/general_educational}/assets/general_educational/subjects/base/subjects.json (100%)
 rename src/usersim/engine/{ => probes/general_educational}/assets/general_educational/subjects/de_DE/subjects.json (100%)
 rename src/usersim/engine/{ => probes/general_educational}/assets/general_educational/subjects/en_GB/subjects.json (100%)
 rename src/usersim/engine/{ => probes/general_educational}/assets/general_educational/subjects/fr_FR/subjects.json (100%)
 rename src/usersim/engine/{ => probes/general_educational}/assets/general_educational/subjects/hi_Deva_IN/subjects.json (100%)
 rename src/usersim/engine/{ => probes/general_educational}/assets/general_educational/subjects/hi_Latn_IN/subjects.json (100%)
 rename src/usersim/engine/{ => probes/general_educational}/assets/general_educational/subjects/ja_JP/subjects.json (100%)
 rename src/usersim/engine/{ => probes/general_educational}/assets/general_educational/subjects/ko_KR/subjects.json (100%)
 rename src/usersim/engine/{ => probes/general_educational}/assets/general_educational/subjects/pt_BR/subjects.json (100%)
 rename src/usersim/engine/probes/general_educational/{generator.py => probe.py} (98%)

diff --git a/architecture/assets.md b/architecture/assets.md
index 2bc73fcf..056dc2bf 100644
--- a/architecture/assets.md
+++ b/architecture/assets.md
@@ -2,7 +2,8 @@
 
 Probe content (fact banks, query banks, pressure banks, clinical profiles,
 finance corpora, tool catalogs, action taxonomies) ships as **package
-data** under `usersim/engine/assets/<probe>/`.
+data** under `usersim/engine/assets/<probe>/`, or, for a built-in probe kept
+in its own folder, under that folder's `assets/<probe>/`.
 
 They ship inside the package so a plain `pip install` gives you working
 probes with no extra download step. `make check-dist` fails if the wheel
@@ -29,10 +30,10 @@ package, such as `Path(__file__).parent / "assets"`, so the probe finds its
 banks wherever the package is installed, with no environment variable to
 set. Registration refuses a relative root. That root is searched for that
 probe only, after the first three entries and before the packaged directory,
-so a deliberate override wins over it. The built-in probes declare none. A
-probe's bank loader reads under its class's `assets_dir()`, the folder this
-search finds for the probe, and its `prompts.yaml` is read from that folder
-too.
+so a deliberate override wins over it. A built-in probe kept in its own
+folder declares one too, that folder's `assets/`. A probe's bank loader reads
+under its class's `assets_dir()`, the folder this search finds for the probe,
+and its `prompts.yaml` is read from that folder too.
 
 An explicit `--assets-dir` is **not** part of the search. It pins resolution
 to exactly that directory, for every probe in the run, including one that
diff --git a/architecture/probes.md b/architecture/probes.md
index 97bbe133..4e6f08a3 100644
--- a/architecture/probes.md
+++ b/architecture/probes.md
@@ -167,7 +167,8 @@ the turn had no side effects.
 
 ## Assets
 
-A probe's content lives at `engine/assets/<label>/`, resolved through
+A probe's content lives at `engine/assets/<label>/`, or, for a probe kept in
+its own folder, at `engine/probes/<label>/assets/<label>/`, resolved through
 `probe_assets_dir()`. A run fails pre-flight, before any model call, if a
 selected probe's bank is missing or, for the probes whose banks are split by
 locale, doesn't load for a run locale (a finance bank without tasks, for
diff --git a/src/usersim/engine/core/_assets.py b/src/usersim/engine/core/_assets.py
index c36bb2af..b55129dd 100644
--- a/src/usersim/engine/core/_assets.py
+++ b/src/usersim/engine/core/_assets.py
@@ -16,7 +16,8 @@
 4. the packaged ``usersim/engine/assets/`` directory.
 
 A probe class may also declare ``assets_root``, the root that holds its
-``<label>/`` folder, as a probe shipped in its own package does. That root
+``<label>/`` folder: a probe shipped in its own package does, and so does a
+built-in probe that keeps its banks in its own folder. That root
 is searched for that probe after the first three entries and before the
 packaged directory, so a deliberate override wins over it.
 
@@ -115,8 +116,9 @@ def asset_search_path() -> tuple[Path, ...]:
 def declared_assets_roots() -> dict[str, Path]:
     """The ``assets_root`` each registered probe class declares, by label.
 
-    Probes that declare none, the built-ins among them, are left out. Reads
-    the registry as it stands, so a probe counts once its module is imported.
+    Probes that declare none, such as a built-in whose banks are in the
+    packaged directory, are left out. Reads the registry as it stands, so a
+    probe counts once its module is imported.
     """
     return {
         label: Path(cls.assets_root)
diff --git a/src/usersim/engine/core/probes.py b/src/usersim/engine/core/probes.py
index ecf067ce..6fe54f9e 100644
--- a/src/usersim/engine/core/probes.py
+++ b/src/usersim/engine/core/probes.py
@@ -294,12 +294,12 @@ def get_assistant_system_prompt(self) -> str:
     default_scorers: tuple[str, ...] = ()
 
     # The directory that holds this probe's ``<label>/`` asset folder, for a
-    # probe whose assets ship outside ``usersim``: an absolute path, such as
-    # ``Path(__file__).parent / "assets"`` (``@register_probe`` refuses a
-    # relative one). Searched after the deliberate overrides (the runtime
-    # override, ``USERSIM_ASSET_PATH`` and ``USERSIM_ASSETS_DIR``) and before
-    # the packaged banks. ``None``, as for every built-in probe, searches the
-    # overrides and the packaged banks only.
+    # probe whose assets are outside the packaged banks, in its own package or
+    # its own folder: an absolute path, such as ``Path(__file__).parent /
+    # "assets"`` (``@register_probe`` refuses a relative one). Searched after
+    # the deliberate overrides (the runtime override, ``USERSIM_ASSET_PATH``
+    # and ``USERSIM_ASSETS_DIR``) and before the packaged banks. ``None``
+    # searches the overrides and the packaged banks only.
     assets_root: Path | None = None
 
     @classmethod
@@ -1541,7 +1541,7 @@ def decorator(cls: type[BaseProbe]) -> type[BaseProbe]:
 #: this one, so this module cannot import them at load time.
 BUILTIN_PROBE_MODULES: tuple[str, ...] = (
     "usersim.engine.probes.financial_services.generator",
-    "usersim.engine.probes.general_educational.generator",
+    "usersim.engine.probes.general_educational.probe",
     "usersim.engine.probes.general_open_ended.generator",
     "usersim.engine.probes.health_disclosure.decision_support",
     "usersim.engine.probes.health_disclosure.general",
diff --git a/src/usersim/engine/assets/general_educational/prompts.yaml b/src/usersim/engine/probes/general_educational/assets/general_educational/prompts.yaml
similarity index 100%
rename from src/usersim/engine/assets/general_educational/prompts.yaml
rename to src/usersim/engine/probes/general_educational/assets/general_educational/prompts.yaml
diff --git a/src/usersim/engine/assets/general_educational/subjects/base/subjects.json b/src/usersim/engine/probes/general_educational/assets/general_educational/subjects/base/subjects.json
similarity index 100%
rename from src/usersim/engine/assets/general_educational/subjects/base/subjects.json
rename to src/usersim/engine/probes/general_educational/assets/general_educational/subjects/base/subjects.json
diff --git a/src/usersim/engine/assets/general_educational/subjects/de_DE/subjects.json b/src/usersim/engine/probes/general_educational/assets/general_educational/subjects/de_DE/subjects.json
similarity index 100%
rename from src/usersim/engine/assets/general_educational/subjects/de_DE/subjects.json
rename to src/usersim/engine/probes/general_educational/assets/general_educational/subjects/de_DE/subjects.json
diff --git a/src/usersim/engine/assets/general_educational/subjects/en_GB/subjects.json b/src/usersim/engine/probes/general_educational/assets/general_educational/subjects/en_GB/subjects.json
similarity index 100%
rename from src/usersim/engine/assets/general_educational/subjects/en_GB/subjects.json
rename to src/usersim/engine/probes/general_educational/assets/general_educational/subjects/en_GB/subjects.json
diff --git a/src/usersim/engine/assets/general_educational/subjects/fr_FR/subjects.json b/src/usersim/engine/probes/general_educational/assets/general_educational/subjects/fr_FR/subjects.json
similarity index 100%
rename from src/usersim/engine/assets/general_educational/subjects/fr_FR/subjects.json
rename to src/usersim/engine/probes/general_educational/assets/general_educational/subjects/fr_FR/subjects.json
diff --git a/src/usersim/engine/assets/general_educational/subjects/hi_Deva_IN/subjects.json b/src/usersim/engine/probes/general_educational/assets/general_educational/subjects/hi_Deva_IN/subjects.json
similarity index 100%
rename from src/usersim/engine/assets/general_educational/subjects/hi_Deva_IN/subjects.json
rename to src/usersim/engine/probes/general_educational/assets/general_educational/subjects/hi_Deva_IN/subjects.json
diff --git a/src/usersim/engine/assets/general_educational/subjects/hi_Latn_IN/subjects.json b/src/usersim/engine/probes/general_educational/assets/general_educational/subjects/hi_Latn_IN/subjects.json
similarity index 100%
rename from src/usersim/engine/assets/general_educational/subjects/hi_Latn_IN/subjects.json
rename to src/usersim/engine/probes/general_educational/assets/general_educational/subjects/hi_Latn_IN/subjects.json
diff --git a/src/usersim/engine/assets/general_educational/subjects/ja_JP/subjects.json b/src/usersim/engine/probes/general_educational/assets/general_educational/subjects/ja_JP/subjects.json
similarity index 100%
rename from src/usersim/engine/assets/general_educational/subjects/ja_JP/subjects.json
rename to src/usersim/engine/probes/general_educational/assets/general_educational/subjects/ja_JP/subjects.json
diff --git a/src/usersim/engine/assets/general_educational/subjects/ko_KR/subjects.json b/src/usersim/engine/probes/general_educational/assets/general_educational/subjects/ko_KR/subjects.json
similarity index 100%
rename from src/usersim/engine/assets/general_educational/subjects/ko_KR/subjects.json
rename to src/usersim/engine/probes/general_educational/assets/general_educational/subjects/ko_KR/subjects.json
diff --git a/src/usersim/engine/assets/general_educational/subjects/pt_BR/subjects.json b/src/usersim/engine/probes/general_educational/assets/general_educational/subjects/pt_BR/subjects.json
similarity index 100%
rename from src/usersim/engine/assets/general_educational/subjects/pt_BR/subjects.json
rename to src/usersim/engine/probes/general_educational/assets/general_educational/subjects/pt_BR/subjects.json
diff --git a/src/usersim/engine/probes/general_educational/generator.py b/src/usersim/engine/probes/general_educational/probe.py
similarity index 98%
rename from src/usersim/engine/probes/general_educational/generator.py
rename to src/usersim/engine/probes/general_educational/probe.py
index 676f701c..e6117715 100644
--- a/src/usersim/engine/probes/general_educational/generator.py
+++ b/src/usersim/engine/probes/general_educational/probe.py
@@ -11,6 +11,7 @@
 
 from __future__ import annotations
 
+from pathlib import Path
 from typing import Any
 
 from usersim.engine.core.behavioral import (
@@ -52,6 +53,7 @@ class EducationalProbe(BaseProbe):
     """
 
     label = "general_educational"
+    assets_root = Path(__file__).parent / "assets"
     description = (
         "Tests tutoring: a persona-grounded learner asks about a subject, and the probe "
         "looks at whether explanations are accurate, pitched at the learner's level and "
diff --git a/src/usersim/engine/probes/tool_calling/generator.py b/src/usersim/engine/probes/tool_calling/generator.py
index 7258e6a0..8bc47abe 100644
--- a/src/usersim/engine/probes/tool_calling/generator.py
+++ b/src/usersim/engine/probes/tool_calling/generator.py
@@ -72,7 +72,7 @@
 logger = logging.getLogger("usersim.engine")
 
 # ── Scenario metadata ────────────────────────────────────────────────
-# See general_educational/generator.py for the contract. `probe_variant` is
+# See general_educational/probe.py for the contract. `probe_variant` is
 # carried on the trajectory; the evaluator reads it for stratification.
 
 PROBE_FAMILY: str = "tool_calling"
diff --git a/tests/engine/core/test_assets_discovery.py b/tests/engine/core/test_assets_discovery.py
index 45cf4f6b..67d6a818 100644
--- a/tests/engine/core/test_assets_discovery.py
+++ b/tests/engine/core/test_assets_discovery.py
@@ -19,8 +19,10 @@
 from __future__ import annotations
 
 import os
+import sys
 from pathlib import Path
 
+import usersim
 from usersim.engine.core._assets import (
     asset_roots_in_use,
     asset_search_path,
@@ -98,8 +100,24 @@ def test_every_registered_probe_resolves_to_a_folder(self) -> None:
         assert not unresolved, f"registered probes without an asset folder: {unresolved}"
 
     def test_every_built_in_probe_ships_its_folder_in_the_package(self) -> None:
-        missing = sorted(label for label in self._labels() if not (packaged_assets_dir() / label).is_dir())
-        assert not missing, f"built-in probes whose assets are not under {packaged_assets_dir()}: {missing}"
+        """In the packaged banks or in the probe's own folder, so a plain install has it."""
+        package = Path(usersim.__file__).parent
+        outside = {
+            label: probe_assets_dir(label)
+            for label in self._labels()
+            if not probe_assets_dir(label).is_relative_to(package)
+        }
+        assert not outside, f"built-in probes whose assets are outside {package}: {outside}"
+
+    def test_a_built_in_that_declares_a_root_keeps_it_in_its_own_folder(self) -> None:
+        """Its banks sit beside its code, at ``engine/probes/<label>/assets/<label>/``."""
+        from usersim.engine.core.probes import resolve_probe
+
+        declared = {label: resolve_probe(label) for label in self._labels() if resolve_probe(label).assets_root}
+        assert declared, "no built-in probe declares an assets_root"
+        for label, cls in declared.items():
+            folder = Path(sys.modules[cls.__module__].__file__).parent
+            assert folder.name == label and Path(cls.assets_root) == folder / "assets", label
 
     def test_packaged_tree_has_no_stray_top_level_entries(self) -> None:
         """Everything shipped under assets/ should be a probe folder. Catches
@@ -241,11 +259,11 @@ def test_a_declared_root_serves_only_its_own_probe(self, register_test_probe, tm
         assert probe_assets_dir("tool_calling") == packaged_assets_dir() / "tool_calling"
 
     def test_roots_in_use_add_declared_roots_after_the_search_path(self, register_test_probe, tmp_path) -> None:
-        assert asset_roots_in_use() == asset_search_path()
-
         register_test_probe("ext_probe", assets_root=tmp_path)
 
-        assert asset_roots_in_use() == (*asset_search_path(), tmp_path)
+        roots, search = asset_roots_in_use(), asset_search_path()
+        assert roots[: len(search)] == search
+        assert tmp_path in roots[len(search) :]
 
 
 class TestProbeAssetsDir:
diff --git a/tests/engine/core/test_multi_locale.py b/tests/engine/core/test_multi_locale.py
index 43def147..42a33ac0 100644
--- a/tests/engine/core/test_multi_locale.py
+++ b/tests/engine/core/test_multi_locale.py
@@ -6,13 +6,12 @@
 import pytest
 
 from usersim.engine.config import ConversationSimulatorConfig
-from usersim.engine.core._assets import packaged_assets_dir
+from usersim.engine.core._assets import probe_assets_dir
 from usersim.engine.core.behavioral import LOCALE_LANGUAGE_MAP, get_conversation_language
 from usersim.engine.core.locale import SHIPPED_LOCALES
 from usersim.engine.core.seeds import load_seeds
 
 LOCALES = SHIPPED_LOCALES
-ASSETS_DIR = packaged_assets_dir()
 
 
 class TestMultiLocaleLoop:
@@ -46,27 +45,28 @@ class TestLocaleSeeds:
 
     @pytest.fixture(autouse=True)
     def check_assets(self):
-        # Fail rather than skip: the seeds are package data, so their absence
-        # is a packaging defect, not an environment the test can excuse.
-        base = ASSETS_DIR / "general_open_ended" / "topics" / "base"
-        assert base.is_dir(), f"packaged seeds missing at {base}"
+        # Fail rather than skip: the seeds ship with the package, so their
+        # absence is a packaging defect, not an environment the test can excuse.
+        for probe, kind in [("general_open_ended", "topics"), ("general_educational", "subjects")]:
+            base = probe_assets_dir(probe) / kind / "base"
+            assert base.is_dir(), f"packaged seeds missing at {base}"
 
     def test_base_seeds_available_for_all_locales(self):
         for locale in LOCALES:
-            topics = load_seeds(locale, "general_open_ended", "topics", ASSETS_DIR)
+            topics = load_seeds(locale, "general_open_ended", "topics")
             assert len(topics) >= 15  # base has 15
 
-            subjects = load_seeds(locale, "general_educational", "subjects", ASSETS_DIR)
+            subjects = load_seeds(locale, "general_educational", "subjects")
             assert len(subjects) >= 10  # base has 10
 
     def test_locale_seed_counts_preserve_localized_replacements(self):
-        base_count = len(load_seeds("en_US", "general_open_ended", "topics", ASSETS_DIR))
-        pt_count = len(load_seeds("pt_BR", "general_open_ended", "topics", ASSETS_DIR))
+        base_count = len(load_seeds("en_US", "general_open_ended", "topics"))
+        pt_count = len(load_seeds("pt_BR", "general_open_ended", "topics"))
         assert base_count == 48
         assert pt_count == 20
 
-        base_ed = len(load_seeds("en_US", "general_educational", "subjects", ASSETS_DIR))
-        ja_ed = len(load_seeds("ja_JP", "general_educational", "subjects", ASSETS_DIR))
+        base_ed = len(load_seeds("en_US", "general_educational", "subjects"))
+        ja_ed = len(load_seeds("ja_JP", "general_educational", "subjects"))
         assert base_ed == 40
         assert ja_ed == 14
 
@@ -76,7 +76,7 @@ def test_seed_kinds_have_required_fields(self):
                 ("general_open_ended", "topics"),
                 ("general_educational", "subjects"),
             ]:
-                seeds = load_seeds(locale, probe, kind, ASSETS_DIR)
+                seeds = load_seeds(locale, probe, kind)
                 for seed in seeds:
                     assert "type" in seed, f"Missing 'type' in {probe}/{kind} for {locale}"
                     assert "description" in seed, f"Missing 'description' in {probe}/{kind} for {locale}"
diff --git a/tests/engine/core/test_prompt_resolution.py b/tests/engine/core/test_prompt_resolution.py
index 317d0025..e2d1cbcf 100644
--- a/tests/engine/core/test_prompt_resolution.py
+++ b/tests/engine/core/test_prompt_resolution.py
@@ -25,7 +25,7 @@
 import pytest
 import yaml
 
-from usersim.engine.core._assets import packaged_assets_dir, probe_assets_dir, set_runtime_assets_dir
+from usersim.engine.core._assets import probe_assets_dir, set_runtime_assets_dir
 from usersim.engine.core.prompt_loader import get_prompt, load_prompt_file, render_prompt
 
 #: The theme-driven probes, mapped to the name each one gives the
@@ -381,7 +381,7 @@ def test_override_is_scoped_to_one_probe(self, tmp_path):
         every other probe on the default."""
         from usersim.engine.core.behavioral import compute_behavioral_profile
         from usersim.engine.core.prompts import ASSISTANT_JUDGE_PROMPT
-        from usersim.engine.probes.general_educational.generator import (
+        from usersim.engine.probes.general_educational.probe import (
             EducationalProbe,
         )
 
@@ -444,5 +444,5 @@ def test_shipped_asset_matches_the_compiled_default(self, probe):
 
         from usersim.engine.core.prompts import ASSISTANT_JUDGE_PROMPT
 
-        shipped = yaml.safe_load((packaged_assets_dir() / probe / "prompts.yaml").read_text())
+        shipped = yaml.safe_load((probe_assets_dir(probe) / "prompts.yaml").read_text())
         assert shipped["assistant_judge_prompt"] == ASSISTANT_JUDGE_PROMPT
diff --git a/tests/engine/core/test_provenance.py b/tests/engine/core/test_provenance.py
index 4b92dbaa..a283c92a 100644
--- a/tests/engine/core/test_provenance.py
+++ b/tests/engine/core/test_provenance.py
@@ -163,7 +163,7 @@ def test_env_override(self, monkeypatch: pytest.MonkeyPatch) -> None:
     "module_path",
     [
         "usersim.engine.probes.general_open_ended.generator",
-        "usersim.engine.probes.general_educational.generator",
+        "usersim.engine.probes.general_educational.probe",
         "usersim.engine.probes.tool_calling.generator",
     ],
 )

From 53ce5544a0103fc10e3167f63549f8030380e0f2 Mon Sep 17 00:00:00 2001
From: Yev Meyer <ymeyer@nvidia.com>
Date: Mon, 2 Nov 2026 16:47:30 -0500
Subject: [PATCH 5/7] refactor(engine): keep general_open_ended in one folder

The probe module is probes/general_open_ended/probe.py and its banks are in probes/general_open_ended/assets/general_open_ended/, the folder the class names as its assets_root. Its label, prompts, topics and stored columns are unchanged.

The two pipeline tests that read its topics load them through the probe's folder, and fail rather than skip when they are missing.

Signed-off-by: Yev Meyer <ymeyer@nvidia.com>
---
 src/usersim/engine/core/probes.py               |  2 +-
 .../engine/probes/general_educational/probe.py  |  2 +-
 .../assets/general_open_ended/prompts.yaml      |  0
 .../general_open_ended/topics/base/topics.json  |  0
 .../general_open_ended/topics/de_DE/topics.json |  0
 .../general_open_ended/topics/en_GB/topics.json |  0
 .../general_open_ended/topics/fr_FR/topics.json |  0
 .../topics/hi_Deva_IN/topics.json               |  0
 .../topics/hi_Latn_IN/topics.json               |  0
 .../general_open_ended/topics/ja_JP/topics.json |  0
 .../general_open_ended/topics/ko_KR/topics.json |  0
 .../general_open_ended/topics/pt_BR/topics.json |  0
 .../{generator.py => probe.py}                  |  2 ++
 tests/engine/core/test_pipeline.py              | 17 +++--------------
 tests/engine/core/test_prompt_resolution.py     |  4 ++--
 tests/engine/core/test_provenance.py            |  2 +-
 tests/engine/core/test_reasoning_replay.py      |  2 +-
 tests/engine/test_undeclared_result_columns.py  |  2 +-
 18 files changed, 12 insertions(+), 21 deletions(-)
 rename src/usersim/engine/{ => probes/general_open_ended}/assets/general_open_ended/prompts.yaml (100%)
 rename src/usersim/engine/{ => probes/general_open_ended}/assets/general_open_ended/topics/base/topics.json (100%)
 rename src/usersim/engine/{ => probes/general_open_ended}/assets/general_open_ended/topics/de_DE/topics.json (100%)
 rename src/usersim/engine/{ => probes/general_open_ended}/assets/general_open_ended/topics/en_GB/topics.json (100%)
 rename src/usersim/engine/{ => probes/general_open_ended}/assets/general_open_ended/topics/fr_FR/topics.json (100%)
 rename src/usersim/engine/{ => probes/general_open_ended}/assets/general_open_ended/topics/hi_Deva_IN/topics.json (100%)
 rename src/usersim/engine/{ => probes/general_open_ended}/assets/general_open_ended/topics/hi_Latn_IN/topics.json (100%)
 rename src/usersim/engine/{ => probes/general_open_ended}/assets/general_open_ended/topics/ja_JP/topics.json (100%)
 rename src/usersim/engine/{ => probes/general_open_ended}/assets/general_open_ended/topics/ko_KR/topics.json (100%)
 rename src/usersim/engine/{ => probes/general_open_ended}/assets/general_open_ended/topics/pt_BR/topics.json (100%)
 rename src/usersim/engine/probes/general_open_ended/{generator.py => probe.py} (98%)

diff --git a/src/usersim/engine/core/probes.py b/src/usersim/engine/core/probes.py
index 6fe54f9e..769461e1 100644
--- a/src/usersim/engine/core/probes.py
+++ b/src/usersim/engine/core/probes.py
@@ -1542,7 +1542,7 @@ def decorator(cls: type[BaseProbe]) -> type[BaseProbe]:
 BUILTIN_PROBE_MODULES: tuple[str, ...] = (
     "usersim.engine.probes.financial_services.generator",
     "usersim.engine.probes.general_educational.probe",
-    "usersim.engine.probes.general_open_ended.generator",
+    "usersim.engine.probes.general_open_ended.probe",
     "usersim.engine.probes.health_disclosure.decision_support",
     "usersim.engine.probes.health_disclosure.general",
     "usersim.engine.probes.health_disclosure.therapy",
diff --git a/src/usersim/engine/probes/general_educational/probe.py b/src/usersim/engine/probes/general_educational/probe.py
index e6117715..9a4130e7 100644
--- a/src/usersim/engine/probes/general_educational/probe.py
+++ b/src/usersim/engine/probes/general_educational/probe.py
@@ -135,7 +135,7 @@ async def simulate_general_educational(
 ) -> dict:
     """Thin shim for callers that import ``simulate_general_educational`` directly.
 
-    See ``usersim.engine.probes.general_open_ended.generator.simulate_general_open_ended``
+    See ``usersim.engine.probes.general_open_ended.probe.simulate_general_open_ended``
     for the rationale; preserved for backward-compat with the dispatcher
     bootstrap and per-probe tests.
     """
diff --git a/src/usersim/engine/assets/general_open_ended/prompts.yaml b/src/usersim/engine/probes/general_open_ended/assets/general_open_ended/prompts.yaml
similarity index 100%
rename from src/usersim/engine/assets/general_open_ended/prompts.yaml
rename to src/usersim/engine/probes/general_open_ended/assets/general_open_ended/prompts.yaml
diff --git a/src/usersim/engine/assets/general_open_ended/topics/base/topics.json b/src/usersim/engine/probes/general_open_ended/assets/general_open_ended/topics/base/topics.json
similarity index 100%
rename from src/usersim/engine/assets/general_open_ended/topics/base/topics.json
rename to src/usersim/engine/probes/general_open_ended/assets/general_open_ended/topics/base/topics.json
diff --git a/src/usersim/engine/assets/general_open_ended/topics/de_DE/topics.json b/src/usersim/engine/probes/general_open_ended/assets/general_open_ended/topics/de_DE/topics.json
similarity index 100%
rename from src/usersim/engine/assets/general_open_ended/topics/de_DE/topics.json
rename to src/usersim/engine/probes/general_open_ended/assets/general_open_ended/topics/de_DE/topics.json
diff --git a/src/usersim/engine/assets/general_open_ended/topics/en_GB/topics.json b/src/usersim/engine/probes/general_open_ended/assets/general_open_ended/topics/en_GB/topics.json
similarity index 100%
rename from src/usersim/engine/assets/general_open_ended/topics/en_GB/topics.json
rename to src/usersim/engine/probes/general_open_ended/assets/general_open_ended/topics/en_GB/topics.json
diff --git a/src/usersim/engine/assets/general_open_ended/topics/fr_FR/topics.json b/src/usersim/engine/probes/general_open_ended/assets/general_open_ended/topics/fr_FR/topics.json
similarity index 100%
rename from src/usersim/engine/assets/general_open_ended/topics/fr_FR/topics.json
rename to src/usersim/engine/probes/general_open_ended/assets/general_open_ended/topics/fr_FR/topics.json
diff --git a/src/usersim/engine/assets/general_open_ended/topics/hi_Deva_IN/topics.json b/src/usersim/engine/probes/general_open_ended/assets/general_open_ended/topics/hi_Deva_IN/topics.json
similarity index 100%
rename from src/usersim/engine/assets/general_open_ended/topics/hi_Deva_IN/topics.json
rename to src/usersim/engine/probes/general_open_ended/assets/general_open_ended/topics/hi_Deva_IN/topics.json
diff --git a/src/usersim/engine/assets/general_open_ended/topics/hi_Latn_IN/topics.json b/src/usersim/engine/probes/general_open_ended/assets/general_open_ended/topics/hi_Latn_IN/topics.json
similarity index 100%
rename from src/usersim/engine/assets/general_open_ended/topics/hi_Latn_IN/topics.json
rename to src/usersim/engine/probes/general_open_ended/assets/general_open_ended/topics/hi_Latn_IN/topics.json
diff --git a/src/usersim/engine/assets/general_open_ended/topics/ja_JP/topics.json b/src/usersim/engine/probes/general_open_ended/assets/general_open_ended/topics/ja_JP/topics.json
similarity index 100%
rename from src/usersim/engine/assets/general_open_ended/topics/ja_JP/topics.json
rename to src/usersim/engine/probes/general_open_ended/assets/general_open_ended/topics/ja_JP/topics.json
diff --git a/src/usersim/engine/assets/general_open_ended/topics/ko_KR/topics.json b/src/usersim/engine/probes/general_open_ended/assets/general_open_ended/topics/ko_KR/topics.json
similarity index 100%
rename from src/usersim/engine/assets/general_open_ended/topics/ko_KR/topics.json
rename to src/usersim/engine/probes/general_open_ended/assets/general_open_ended/topics/ko_KR/topics.json
diff --git a/src/usersim/engine/assets/general_open_ended/topics/pt_BR/topics.json b/src/usersim/engine/probes/general_open_ended/assets/general_open_ended/topics/pt_BR/topics.json
similarity index 100%
rename from src/usersim/engine/assets/general_open_ended/topics/pt_BR/topics.json
rename to src/usersim/engine/probes/general_open_ended/assets/general_open_ended/topics/pt_BR/topics.json
diff --git a/src/usersim/engine/probes/general_open_ended/generator.py b/src/usersim/engine/probes/general_open_ended/probe.py
similarity index 98%
rename from src/usersim/engine/probes/general_open_ended/generator.py
rename to src/usersim/engine/probes/general_open_ended/probe.py
index e9aeacc0..4051919d 100644
--- a/src/usersim/engine/probes/general_open_ended/generator.py
+++ b/src/usersim/engine/probes/general_open_ended/probe.py
@@ -11,6 +11,7 @@
 
 from __future__ import annotations
 
+from pathlib import Path
 from typing import Any
 
 from usersim.engine.core.behavioral import (
@@ -51,6 +52,7 @@ class OpenEndedProbe(BaseProbe):
     """
 
     label = "general_open_ended"
+    assets_root = Path(__file__).parent / "assets"
     description = (
         "Tests information-seeking conversations across diverse personas: accurate, "
         "coherent answers pitched to the user's apparent expertise, and a clarifying "
diff --git a/tests/engine/core/test_pipeline.py b/tests/engine/core/test_pipeline.py
index 75d9fb6f..fa9b6fc0 100644
--- a/tests/engine/core/test_pipeline.py
+++ b/tests/engine/core/test_pipeline.py
@@ -8,10 +8,7 @@
 and are marked with @pytest.mark.integration.
 """
 
-import pytest
-
 from usersim.engine.config import ConversationSimulatorConfig
-from usersim.engine.core._assets import packaged_assets_dir
 from usersim.engine.core.behavioral import compute_behavioral_profile, get_conversation_language
 from usersim.engine.core.locale import SHIPPED_LOCALES
 from usersim.engine.core.seeds import load_seeds
@@ -111,23 +108,15 @@ class TestMultiLocaleConsistency:
     """Verify multi-locale support is consistent."""
 
     def test_seed_loading_per_locale(self):
-        assets = packaged_assets_dir()
-        if not (assets / "general_open_ended" / "topics" / "base").exists():
-            pytest.skip("Assets directory not found")
-
         for locale in SHIPPED_LOCALES:
-            topics = load_seeds(locale, "general_open_ended", "topics", assets)
+            topics = load_seeds(locale, "general_open_ended", "topics")
             assert len(topics) > 0
             assert all(isinstance(t, dict) for t in topics)
             assert all("type" in t and "description" in t for t in topics)
 
     def test_pt_br_keeps_localized_topic_replacement(self):
-        assets = packaged_assets_dir()
-        if not (assets / "general_open_ended" / "topics" / "base").exists():
-            pytest.skip("Assets directory not found")
-
-        base = load_seeds("en_US", "general_open_ended", "topics", assets)
-        extended = load_seeds("pt_BR", "general_open_ended", "topics", assets)
+        base = load_seeds("en_US", "general_open_ended", "topics")
+        extended = load_seeds("pt_BR", "general_open_ended", "topics")
         assert len(base) == 48
         assert len(extended) == 20
 
diff --git a/tests/engine/core/test_prompt_resolution.py b/tests/engine/core/test_prompt_resolution.py
index e2d1cbcf..4c4402b7 100644
--- a/tests/engine/core/test_prompt_resolution.py
+++ b/tests/engine/core/test_prompt_resolution.py
@@ -198,7 +198,7 @@ class _Cfg:
 def _open_ended_probe(data: dict):
     """A real ``OpenEndedProbe`` for ``data``, with no LLM anywhere near it."""
     from usersim.engine.core.behavioral import compute_behavioral_profile
-    from usersim.engine.probes.general_open_ended.generator import OpenEndedProbe
+    from usersim.engine.probes.general_open_ended.probe import OpenEndedProbe
 
     persona = {"first_name": "A", "last_name": "B", "age": 30, "sex": "female"}
     return OpenEndedProbe(
@@ -281,7 +281,7 @@ def test_each_row_renders_its_own_values(self, tmp_path):
         """The dispatcher constructs a probe per row, so a row column
         referenced from prompts.yaml must reflect THAT row."""
         from usersim.engine.core.behavioral import compute_behavioral_profile
-        from usersim.engine.probes.general_open_ended.generator import (
+        from usersim.engine.probes.general_open_ended.probe import (
             OpenEndedProbe,
         )
 
diff --git a/tests/engine/core/test_provenance.py b/tests/engine/core/test_provenance.py
index a283c92a..d320a452 100644
--- a/tests/engine/core/test_provenance.py
+++ b/tests/engine/core/test_provenance.py
@@ -162,7 +162,7 @@ def test_env_override(self, monkeypatch: pytest.MonkeyPatch) -> None:
 @pytest.mark.parametrize(
     "module_path",
     [
-        "usersim.engine.probes.general_open_ended.generator",
+        "usersim.engine.probes.general_open_ended.probe",
         "usersim.engine.probes.general_educational.probe",
         "usersim.engine.probes.tool_calling.generator",
     ],
diff --git a/tests/engine/core/test_reasoning_replay.py b/tests/engine/core/test_reasoning_replay.py
index c60469b3..9f9639e2 100644
--- a/tests/engine/core/test_reasoning_replay.py
+++ b/tests/engine/core/test_reasoning_replay.py
@@ -158,7 +158,7 @@ async def test_a_hosted_episode_replays_as_a_local_one_does(probe_type):
 async def test_a_probe_shortcut_replays_as_the_generator_does():
     """The public ``simulate_<probe>`` functions promise the dispatcher path's behaviour."""
     from usersim.engine.core.episode_input import construct_episode_preamble
-    from usersim.engine.probes.general_open_ended.generator import simulate_general_open_ended
+    from usersim.engine.probes.general_open_ended.probe import simulate_general_open_ended
 
     cfg = _config("general_open_ended", replay_assistant_reasoning=True)
     prompts: list[dict[str, Any]] = []
diff --git a/tests/engine/test_undeclared_result_columns.py b/tests/engine/test_undeclared_result_columns.py
index c3f715a5..7c45596a 100644
--- a/tests/engine/test_undeclared_result_columns.py
+++ b/tests/engine/test_undeclared_result_columns.py
@@ -27,7 +27,7 @@
 from usersim.engine.core.episode_input import ConstructedEpisode
 from usersim.engine.core.probes import _PROBE_REGISTRY, clear_registry, load_builtin_probes, register_probe
 from usersim.engine.generator import ConversationSimulatorGenerator
-from usersim.engine.probes.general_open_ended.generator import OpenEndedProbe
+from usersim.engine.probes.general_open_ended.probe import OpenEndedProbe
 
 _PROBE = "_extra_column_probe"
 _PERSONA = {"first_name": "Sarah", "last_name": "Johnson", "age": 35, "city": "Seattle", "state": "WA"}

From ef01cb235b137f64cb8465b25e188d00a596f96f Mon Sep 17 00:00:00 2001
From: Yev Meyer <ymeyer@nvidia.com>
Date: Mon, 2 Nov 2026 16:47:38 -0500
Subject: [PATCH 6/7] docs(engine): show the one-folder probe layout in the
 guide and template

Step 2 of the authoring guide has a probe keep its banks beside its code and set assets_root, and the worked bookings example is laid out that way, with probe.py and its banks in assets/bookings/. The probe template is copied to probe.py, the templates that load a bank declare assets_root, and notebook 01 says each probe's assets ship with the package.

Signed-off-by: Yev Meyer <ymeyer@nvidia.com>
---
 docs/engine/AUTHORING_A_PROBE.md            | 25 +++++++++++++--------
 notebooks/01_simulate.ipynb                 |  2 +-
 templates/probe/README.md                   | 12 +++++-----
 templates/probe/generator_agentic.py        |  2 ++
 templates/probe/generator_bank_reframing.py |  2 ++
 templates/probe/generator_bank_verbatim.py  |  1 +
 templates/probe/generator_custom_turn1.py   |  2 ++
 templates/probe/test_probe.py.template      |  2 +-
 tests/test_extension_api.py                 |  2 +-
 9 files changed, 33 insertions(+), 17 deletions(-)

diff --git a/docs/engine/AUTHORING_A_PROBE.md b/docs/engine/AUTHORING_A_PROBE.md
index b26ccff9..85ebca6d 100644
--- a/docs/engine/AUTHORING_A_PROBE.md
+++ b/docs/engine/AUTHORING_A_PROBE.md
@@ -232,9 +232,9 @@ class MyProbe(BankBackedProbe):
     )
 ```
 
-A probe shipped in its own package, rather than in this repository, also
-sets `assets_root` to the directory that holds its `<label>/` asset folder,
-so it finds its banks wherever the package is installed:
+A probe keeps its banks beside its code and sets `assets_root` to the
+directory that holds its `<label>/` asset folder, so it finds them wherever
+its code is installed, in this repository or in a package of its own:
 
 ```python
 from pathlib import Path
@@ -245,8 +245,10 @@ class MyProbe(BaseProbe):
 ```
 
 It must be absolute: `@register_probe` refuses a relative path, which would
-resolve against the working directory. Built-in probes leave it unset: their
-banks are under `src/usersim/engine/assets/<label>/`.
+resolve against the working directory. In this repository the banks are then
+at `src/usersim/engine/probes/<label>/assets/<label>/`, as for
+`general_educational` and `general_open_ended`. A built-in that leaves
+`assets_root` unset keeps its banks under `src/usersim/engine/assets/<label>/`.
 
 Its bank loader reads under `MyProbe.assets_dir()`, the probe's own folder,
 resolved as the built-in loaders resolve theirs, so a folder `--assets-dir` or
@@ -309,7 +311,7 @@ If your tests want to monkeypatch the loader, point at a module-level
 alias (not the class attr directly):
 
 ```python
-# In your generator.py
+# In your probe.py
 from usersim.engine.probes.my_probe.bank import load_my_bank_default
 
 _load_bank = load_my_bank_default  # tests patch this name
@@ -633,7 +635,7 @@ We'll use the **banked-verbatim** shape, so each date reaches the assistant
 exactly as the bank writes it, with `ToolExecutionMixin` to answer the
 assistant's tool call.
 
-### File 1: the banks, `src/usersim/engine/assets/bookings/<locale>/bookings.yaml`
+### File 1: the banks, `src/usersim/engine/probes/bookings/assets/bookings/<locale>/bookings.yaml`
 
 `en_US/bookings.yaml`:
 
@@ -742,7 +744,7 @@ BOOKINGS_USER_PROMPTS = LocalePromptPack(
 The user's instructions are written in each language the probe ships, and
 `LocalePromptPack` refuses, when the module is imported, a locale without them.
 
-### File 5: `src/usersim/engine/probes/bookings/generator.py`
+### File 5: `src/usersim/engine/probes/bookings/probe.py`
 
 ```python
 """bookings probe: booking arguments from dates and times as users write them."""
@@ -751,6 +753,7 @@ from __future__ import annotations
 
 import json
 import random
+from pathlib import Path
 from typing import Any
 
 from usersim.engine.core.probes import dispatch_episode
@@ -803,6 +806,7 @@ def _bank_loader(locale: str):
 )
 class BookingsProbe(ToolExecutionMixin, BankVerbatimMixin, BankBackedProbe):
     label = "bookings"
+    assets_root = Path(__file__).parent / "assets"  # holds bookings/
     description = (
         "Tests whether an assistant books what the user means: a date, a time and a number of people, "
         "written the way people write them in the user's language."
@@ -893,6 +897,9 @@ async def simulate_bookings(
     return await dispatch_episode(probe, models=models, data=data, cfg=cfg)
 ```
 
+- `assets_root` names the folder beside the module that holds `bookings/`, so
+  the probe finds its banks wherever User Sim is installed, and the loader
+  reads them under `BookingsProbe.assets_dir()`.
 - `execute_tool_call` records the first booking in `state.metadata` during the
   run, with how many user turns came before it, and `build_result_extras`
   writes it to the `booking` column beside what the user meant. A scorer
@@ -924,7 +931,7 @@ add the module to `BUILTIN_PROBE_MODULES`:
 ```python
 BUILTIN_PROBE_MODULES: tuple[str, ...] = (
     ...
-    "usersim.engine.probes.bookings.generator",
+    "usersim.engine.probes.bookings.probe",
 )
 ```
 
diff --git a/notebooks/01_simulate.ipynb b/notebooks/01_simulate.ipynb
index 2c2a8ca0..9c01e6cd 100644
--- a/notebooks/01_simulate.ipynb
+++ b/notebooks/01_simulate.ipynb
@@ -22,7 +22,7 @@
     "\n",
     "- `NVIDIA_API_KEY` exported in your shell (or set in the cell below).\n",
     "- The Nemotron-Personas dataset for the locales you care about. The setup cell below downloads any missing locales the first time via the NGC CLI; if `ngc` isn't on `PATH` it auto-installs into `.venv/bin/` (or run `usersim setup-ngc` ahead of time, per the README).\n",
-    "- An `assets/` directory with one folder per probe (`assets/<probe>/`). These ship with the repo.\n",
+    "- Each probe's assets, in an `assets/<probe>/` folder. These ship with the package.\n",
     "\n",
     "**What this writes:**\n",
     "\n",
diff --git a/templates/probe/README.md b/templates/probe/README.md
index f004d6f9..942e7e9b 100644
--- a/templates/probe/README.md
+++ b/templates/probe/README.md
@@ -44,8 +44,9 @@ templates/probe/
 
 When you port the template, copy the `generator_<shape>.py` whose
 shape matches your probe into
-`src/usersim/engine/probes/<your_probe>/generator.py`,
-copy `prompts.py` into the same directory, and copy
+`src/usersim/engine/probes/<your_probe>/probe.py`,
+copy `prompts.py` into the same directory, put its banks in that
+directory's `assets/<your_probe>/`, and copy
 `test_probe.py.template` to
 `tests/engine/probes/test_<your_probe>.py`. Then follow the
 authoring tutorial.
@@ -56,9 +57,10 @@ A probe class is a `BaseProbe` subclass (plus an optional mixin)
 decorated with `@register_probe(...)`. The decorator sets three
 class attributes (`family` / `prompt_version` / `variants`); the
 smoke check verifies they're present. A probe ported from this template
-keeps its banks under `src/usersim/engine/assets/<your_probe>/` and leaves
-`assets_root` unset; a probe shipped in its own package sets it, and its
-bank loader reads under `assets_dir()`, as
+keeps its banks beside its code, under
+`src/usersim/engine/probes/<your_probe>/assets/<your_probe>/`, and sets
+`assets_root` to that `assets/` folder, as a probe shipped in its own
+package does. Its bank loader reads under `assets_dir()`, as
 `docs/engine/AUTHORING_A_PROBE.md` step 2 shows.
 
 The runtime `ProbeAdapter` contract has 8 required hooks: class-level
diff --git a/templates/probe/generator_agentic.py b/templates/probe/generator_agentic.py
index 5eef7edc..4cf22af6 100644
--- a/templates/probe/generator_agentic.py
+++ b/templates/probe/generator_agentic.py
@@ -47,6 +47,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
+from pathlib import Path
 from typing import Any
 
 from usersim.extension import (
@@ -84,6 +85,7 @@ class DemoAgenticProbe(AgenticMixin, BankBackedProbe):
     """Single-user-turn + multi-assistant-turn tool-interception probe."""
 
     label = "demo_agentic"
+    assets_root = Path(__file__).parent / "assets"  # holds demo_agentic/, beside this module
     output_columns = ("action_request_id", "sub_protocol")
     bank_loader = staticmethod(_demo_agentic_loader)
     placeholder_warning_kind = WarningKind.USED_PLACEHOLDER_AGENTIC_ACTION
diff --git a/templates/probe/generator_bank_reframing.py b/templates/probe/generator_bank_reframing.py
index 0fda1ff4..b5447fff 100644
--- a/templates/probe/generator_bank_reframing.py
+++ b/templates/probe/generator_bank_reframing.py
@@ -59,6 +59,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
+from pathlib import Path
 from typing import Any
 
 from usersim.extension import (
@@ -116,6 +117,7 @@ class DemoBankReframingProbe(BankReframingMixin, BankBackedProbe):
     """Multi-turn reframing-rotation probe."""
 
     label = "demo_bank_reframing"
+    assets_root = Path(__file__).parent / "assets"  # holds demo_bank_reframing/, beside this module
     output_columns = ("target_request_id", "strategy_id", "reframings_used")
     bank_loader = staticmethod(_demo_pressure_loader)
     placeholder_warning_kind = WarningKind.USED_PLACEHOLDER_TARGET
diff --git a/templates/probe/generator_bank_verbatim.py b/templates/probe/generator_bank_verbatim.py
index cd13026c..29d4013f 100644
--- a/templates/probe/generator_bank_verbatim.py
+++ b/templates/probe/generator_bank_verbatim.py
@@ -103,6 +103,7 @@ class DemoBankVerbatimProbe(BankVerbatimMixin, BankBackedProbe):
     """
 
     label = "demo_bank_verbatim"
+    assets_root = Path(__file__).parent / "assets"  # holds demo_bank_verbatim/, beside this module
     output_columns = ("sovereign_facts_probed",)
     bank_loader = staticmethod(_demo_bank_loader)
     placeholder_warning_kind = WarningKind.USED_PLACEHOLDER_FACT
diff --git a/templates/probe/generator_custom_turn1.py b/templates/probe/generator_custom_turn1.py
index c80f5084..0a5f3737 100644
--- a/templates/probe/generator_custom_turn1.py
+++ b/templates/probe/generator_custom_turn1.py
@@ -42,6 +42,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
+from pathlib import Path
 from typing import Any
 
 from usersim.extension import BankBackedProbe, WarningKind, register_probe
@@ -68,6 +69,7 @@ class DemoCustomTurn1Probe(BankBackedProbe):
     """Bank-anchored, generated-in-voice turn-1 probe."""
 
     label = "demo_custom_turn1"
+    assets_root = Path(__file__).parent / "assets"  # holds demo_custom_turn1/, beside this module
     output_columns = ("probing_categories_explored", "probing_subtopic_hints_used")
     bank_loader = staticmethod(_demo_taxonomy_loader)
     placeholder_warning_kind = WarningKind.USED_PLACEHOLDER_TAXONOMY
diff --git a/templates/probe/test_probe.py.template b/templates/probe/test_probe.py.template
index c9b64423..c22c5b79 100644
--- a/templates/probe/test_probe.py.template
+++ b/templates/probe/test_probe.py.template
@@ -65,7 +65,7 @@ from usersim.testing import assert_probe_conforms, run_episode
 
 # Replace with your probe's module + names.
 from usersim.engine.probes.YOUR_PROBE import (
-    generator as probe_gen,
+    probe as probe_gen,
 )
 
 PROBE_LABEL = "YOUR_PROBE"
diff --git a/tests/test_extension_api.py b/tests/test_extension_api.py
index e965bb99..f4d700a6 100644
--- a/tests/test_extension_api.py
+++ b/tests/test_extension_api.py
@@ -53,7 +53,7 @@
 #: Imports from other ``usersim`` modules that the examples keep, as (module, name).
 _KEPT_INTERNAL_IMPORTS = {
     # A new in-tree probe's own modules, under the names the examples give them.
-    ("usersim.engine.probes.YOUR_PROBE", "generator"),
+    ("usersim.engine.probes.YOUR_PROBE", "probe"),
     ("usersim.engine.probes.bookings.bank", "LOCALES"),
     ("usersim.engine.probes.bookings.bank", "Booking"),
     ("usersim.engine.probes.bookings.bank", "read_booking_bank"),

From 8da2e5db27b8baf5d038dbd0371b21025b67ff7e Mon Sep 17 00:00:00 2001
From: Yev Meyer <ymeyer@nvidia.com>
Date: Mon, 2 Nov 2026 17:47:13 -0500
Subject: [PATCH 7/7] refactor(engine): keep the general probes' seeds in
 locale folders

general_open_ended keeps its topics in <locale>/topics.json and general_educational its subjects in <locale>/subjects.json, one folder per locale under each probe's assets, as the other locale-keyed probes lay out their banks. The English file is in en_US/, and load_seeds reads it for a locale that ships no file of its own, such as en_IN and en_SG. The seed files' contents are unchanged.

The seed tests build the same layout, and the engine README and notebook 01 name the new paths.

Signed-off-by: Yev Meyer <ymeyer@nvidia.com>
---
 docs/engine/README.md                         |  4 +-
 notebooks/01_simulate.ipynb                   |  4 +-
 src/usersim/engine/core/seeds.py              | 58 +++++++++----------
 .../{subjects => }/de_DE/subjects.json        |  0
 .../{subjects => }/en_GB/subjects.json        |  0
 .../{subjects/base => en_US}/subjects.json    |  0
 .../{subjects => }/fr_FR/subjects.json        |  0
 .../{subjects => }/hi_Deva_IN/subjects.json   |  0
 .../{subjects => }/hi_Latn_IN/subjects.json   |  0
 .../{subjects => }/ja_JP/subjects.json        |  0
 .../{subjects => }/ko_KR/subjects.json        |  0
 .../{subjects => }/pt_BR/subjects.json        |  0
 .../probes/general_educational/probe.py       |  2 +-
 .../{topics => }/de_DE/topics.json            |  0
 .../{topics => }/en_GB/topics.json            |  0
 .../{topics/base => en_US}/topics.json        |  0
 .../{topics => }/fr_FR/topics.json            |  0
 .../{topics => }/hi_Deva_IN/topics.json       |  0
 .../{topics => }/hi_Latn_IN/topics.json       |  0
 .../{topics => }/ja_JP/topics.json            |  0
 .../{topics => }/ko_KR/topics.json            |  0
 .../{topics => }/pt_BR/topics.json            |  0
 .../engine/probes/general_open_ended/probe.py |  2 +-
 tests/engine/core/test_default_asset_paths.py |  2 +-
 tests/engine/core/test_multi_locale.py        | 20 +++----
 tests/engine/core/test_seeds.py               | 30 +++++-----
 26 files changed, 61 insertions(+), 61 deletions(-)
 rename src/usersim/engine/probes/general_educational/assets/general_educational/{subjects => }/de_DE/subjects.json (100%)
 rename src/usersim/engine/probes/general_educational/assets/general_educational/{subjects => }/en_GB/subjects.json (100%)
 rename src/usersim/engine/probes/general_educational/assets/general_educational/{subjects/base => en_US}/subjects.json (100%)
 rename src/usersim/engine/probes/general_educational/assets/general_educational/{subjects => }/fr_FR/subjects.json (100%)
 rename src/usersim/engine/probes/general_educational/assets/general_educational/{subjects => }/hi_Deva_IN/subjects.json (100%)
 rename src/usersim/engine/probes/general_educational/assets/general_educational/{subjects => }/hi_Latn_IN/subjects.json (100%)
 rename src/usersim/engine/probes/general_educational/assets/general_educational/{subjects => }/ja_JP/subjects.json (100%)
 rename src/usersim/engine/probes/general_educational/assets/general_educational/{subjects => }/ko_KR/subjects.json (100%)
 rename src/usersim/engine/probes/general_educational/assets/general_educational/{subjects => }/pt_BR/subjects.json (100%)
 rename src/usersim/engine/probes/general_open_ended/assets/general_open_ended/{topics => }/de_DE/topics.json (100%)
 rename src/usersim/engine/probes/general_open_ended/assets/general_open_ended/{topics => }/en_GB/topics.json (100%)
 rename src/usersim/engine/probes/general_open_ended/assets/general_open_ended/{topics/base => en_US}/topics.json (100%)
 rename src/usersim/engine/probes/general_open_ended/assets/general_open_ended/{topics => }/fr_FR/topics.json (100%)
 rename src/usersim/engine/probes/general_open_ended/assets/general_open_ended/{topics => }/hi_Deva_IN/topics.json (100%)
 rename src/usersim/engine/probes/general_open_ended/assets/general_open_ended/{topics => }/hi_Latn_IN/topics.json (100%)
 rename src/usersim/engine/probes/general_open_ended/assets/general_open_ended/{topics => }/ja_JP/topics.json (100%)
 rename src/usersim/engine/probes/general_open_ended/assets/general_open_ended/{topics => }/ko_KR/topics.json (100%)
 rename src/usersim/engine/probes/general_open_ended/assets/general_open_ended/{topics => }/pt_BR/topics.json (100%)

diff --git a/docs/engine/README.md b/docs/engine/README.md
index 91046df8..6e23a394 100644
--- a/docs/engine/README.md
+++ b/docs/engine/README.md
@@ -554,7 +554,7 @@ what each one carries:
 | `core/pressure_bank.py` | Pressure-strategy bank loader (Strategy / Reframing / TargetRequest), template-placeholder validator, deterministic per-turn reframing rotation, persona-tag matcher (consumed by `safety_chat_pressure`) |
 | `core/agentic_bank.py` | Agentic-action bank loader (SubProtocol / ToolSpec / ActionRequest), JSON-Schema tool-spec validator, mock-response cross-reference validator, **action-taxonomy name resolution at load time** (rejects banks that reference an unknown action), persona-tag matcher (consumed by `safety_agentic`) |
 | `core/action_taxonomy.py` | Rich action-taxonomy loader (categories, risk tiers, blast-radius ranks); consumed by the `safety_agentic` scorer for cross-asset action classification |
-| `core/seeds.py` | Hybrid seed-data loading (per-probe `base/` + per-locale extensions merged at runtime) |
+| `core/seeds.py` | Seed loading: a probe's `<locale>/<kind>.json`, or the `en_US` file for a locale without one |
 | `core/analysis.py` | Helpers for the deep-dive analysis script |
 
 ## Testing
@@ -593,7 +593,7 @@ plugin entry points, undeclared result columns). The tables describe the main fi
 | `test_messages.py` | Message / tool / theme formatting helpers |
 | `test_persona.py` | Persona formatting (deterministic shuffle) |
 | `test_preview.py` | Rich-based preview rendering for inspecting generated conversations |
-| `test_seeds.py` | Hybrid seed loading and merging (per-probe `base/` + per-locale extensions) |
+| `test_seeds.py` | Seed loading by locale, and the `en_US` fallback |
 | `test_multi_locale.py` | Multi-locale config, seed loading, language mapping |
 | `test_llm.py` | LLM call helpers (retries, debug log, per-model stats, per-conversation outcome-builder hook) |
 | `test_analysis.py` | Score extraction, demographic preservation, edge cases used by the deep-dive analysis script |
diff --git a/notebooks/01_simulate.ipynb b/notebooks/01_simulate.ipynb
index 9c01e6cd..fe69a091 100644
--- a/notebooks/01_simulate.ipynb
+++ b/notebooks/01_simulate.ipynb
@@ -33,8 +33,8 @@
     "| Family | Probe | Curated asset | When to use |\n",
     "|---|---|---|---|\n",
     "| General | `tool_calling` | `assets/tool_calling/toolsets_seed.parquet` | Tests native tool-call selection + arg synthesis on persona-grounded requests |\n",
-    "| General | `general_open_ended` | `assets/general_open_ended/topics/<locale>/topics.json` | Tests multi-turn conversational quality on open-ended topics |\n",
-    "| General | `general_educational` | `assets/general_educational/subjects/<locale>/subjects.json` | Tests pedagogical responses (level-calibration, scaffolded explanations) |\n",
+    "| General | `general_open_ended` | `assets/general_open_ended/<locale>/topics.json` | Tests multi-turn conversational quality on open-ended topics |\n",
+    "| General | `general_educational` | `assets/general_educational/<locale>/subjects.json` | Tests pedagogical responses (level-calibration, scaffolded explanations) |\n",
     "| Sovereign-AI | `sov_ai_facts` | `assets/sov_ai_facts/<locale>/` | Per-locale fact bank with curated ground truth + false-premise probes |\n",
     "| Sovereign-AI | `sov_ai_dynamic` | `assets/sov_ai_dynamic/<locale>/` | Persona-driven exploration with no ground truth: surfaces hallucination / self-inconsistency |\n",
     "| Sovereign-AI | `sov_ai_multilingual_parity` | `assets/sov_ai_multilingual_parity/sample.yaml` | Cross-locale matched-pair queries: surfaces respect-parity gaps across demographic strata |\n",
diff --git a/src/usersim/engine/core/seeds.py b/src/usersim/engine/core/seeds.py
index dd4e588b..72ee3e42 100644
--- a/src/usersim/engine/core/seeds.py
+++ b/src/usersim/engine/core/seeds.py
@@ -1,20 +1,18 @@
 # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 
-"""Per-probe seed loader with locale-aware replacement.
+"""Per-probe seed loader, one file per locale.
 
-Seeds for a given probe live under
-``assets/<probe>/<kind>/<locale>/<kind>.json``, with a
-``<probe>/<kind>/base/<kind>.json`` fallback for locales that don't
-ship a translated version. The ``base`` file is treated as the default
-(English-language) source; locale-specific files are **complete
-replacements** (containing both translated universals and locale-only
-additions) so descriptions are always in the target language.
+A probe's seeds live in ``<probe>/<locale>/<kind>.json``, one folder per
+locale, and a locale without a file of its own reads the
+``FALLBACK_LOCALE`` file. Each locale's file is a complete set
+(translated universals and locale-only additions), not additions to the
+fallback, so descriptions are always in the target language.
 
 Concrete shipped layouts:
 
-- ``assets/general_open_ended/topics/{base,<locale>}/topics.json``
-- ``assets/general_educational/subjects/{base,<locale>}/subjects.json``
+- ``general_open_ended/<locale>/topics.json``
+- ``general_educational/<locale>/subjects.json``
 
 API:
 
@@ -28,6 +26,9 @@
 from pathlib import Path
 from typing import Any
 
+FALLBACK_LOCALE = "en_US"
+"""The locale whose seed file a locale without its own file reads."""
+
 
 def load_seeds(
     locale: str,
@@ -35,48 +36,47 @@ def load_seeds(
     kind: str,
     assets_dir: Path | str | None = None,
 ) -> list[dict[str, Any]]:
-    """Load seed data for ``(probe, kind)`` with locale-aware replacement.
+    """Load ``locale``'s ``kind`` seeds for ``probe``.
 
     Path resolution:
 
-    1. ``<assets>/<probe>/<kind>/<locale>/<kind>.json`` — used if it exists.
-    2. ``<assets>/<probe>/<kind>/base/<kind>.json`` — fallback otherwise
-       (covers ``en_US`` and any locale without its own translation).
+    1. ``<probe>/<locale>/<kind>.json``, used if it exists.
+    2. ``<probe>/en_US/<kind>.json`` otherwise, for any locale that
+       ships no file of its own.
 
     Args:
         locale: The locale code (e.g., ``"en_US"``, ``"pt_BR"``).
-        probe: The owning probe directory under ``assets/`` (e.g.,
-            ``"general_open_ended"``, ``"general_educational"``).
-        kind: The seed file basename (and the inner directory name),
-            e.g. ``"topics"`` or ``"subjects"``.
-        assets_dir: Override the shipped ``assets/`` root. Defaults to
-            the discovered shipped directory.
+        probe: The probe's label (e.g., ``"general_open_ended"``,
+            ``"general_educational"``).
+        kind: The seed file's basename, e.g. ``"topics"`` or ``"subjects"``.
+        assets_dir: A root holding ``<probe>/``. Defaults to the folder
+            ``probe_assets_dir`` resolves for the probe.
 
     Returns:
         List of seed dicts in the target language.
 
     Raises:
-        FileNotFoundError: If neither locale-specific nor base seed file
-            exists for the requested ``(probe, kind)``.
+        FileNotFoundError: If neither the locale's file nor the
+            ``FALLBACK_LOCALE`` file exists for ``(probe, kind)``.
     """
     if assets_dir is not None:
-        base = Path(assets_dir) / probe / kind
+        probe_dir = Path(assets_dir) / probe
     else:
         from usersim.engine.core._assets import probe_assets_dir
 
-        base = probe_assets_dir(probe) / kind
+        probe_dir = probe_assets_dir(probe)
 
-    locale_path = base / locale / f"{kind}.json"
+    locale_path = probe_dir / locale / f"{kind}.json"
     if locale_path.exists():
         with open(locale_path) as f:
             return json.load(f)
 
-    base_path = base / "base" / f"{kind}.json"
-    if not base_path.exists():
+    fallback_path = probe_dir / FALLBACK_LOCALE / f"{kind}.json"
+    if not fallback_path.exists():
         raise FileNotFoundError(
             f"Seed file not found for probe={probe!r} kind={kind!r} "
-            f"locale={locale!r}: checked {locale_path} and {base_path}"
+            f"locale={locale!r}: checked {locale_path} and {fallback_path}"
         )
 
-    with open(base_path) as f:
+    with open(fallback_path) as f:
         return json.load(f)
diff --git a/src/usersim/engine/probes/general_educational/assets/general_educational/subjects/de_DE/subjects.json b/src/usersim/engine/probes/general_educational/assets/general_educational/de_DE/subjects.json
similarity index 100%
rename from src/usersim/engine/probes/general_educational/assets/general_educational/subjects/de_DE/subjects.json
rename to src/usersim/engine/probes/general_educational/assets/general_educational/de_DE/subjects.json
diff --git a/src/usersim/engine/probes/general_educational/assets/general_educational/subjects/en_GB/subjects.json b/src/usersim/engine/probes/general_educational/assets/general_educational/en_GB/subjects.json
similarity index 100%
rename from src/usersim/engine/probes/general_educational/assets/general_educational/subjects/en_GB/subjects.json
rename to src/usersim/engine/probes/general_educational/assets/general_educational/en_GB/subjects.json
diff --git a/src/usersim/engine/probes/general_educational/assets/general_educational/subjects/base/subjects.json b/src/usersim/engine/probes/general_educational/assets/general_educational/en_US/subjects.json
similarity index 100%
rename from src/usersim/engine/probes/general_educational/assets/general_educational/subjects/base/subjects.json
rename to src/usersim/engine/probes/general_educational/assets/general_educational/en_US/subjects.json
diff --git a/src/usersim/engine/probes/general_educational/assets/general_educational/subjects/fr_FR/subjects.json b/src/usersim/engine/probes/general_educational/assets/general_educational/fr_FR/subjects.json
similarity index 100%
rename from src/usersim/engine/probes/general_educational/assets/general_educational/subjects/fr_FR/subjects.json
rename to src/usersim/engine/probes/general_educational/assets/general_educational/fr_FR/subjects.json
diff --git a/src/usersim/engine/probes/general_educational/assets/general_educational/subjects/hi_Deva_IN/subjects.json b/src/usersim/engine/probes/general_educational/assets/general_educational/hi_Deva_IN/subjects.json
similarity index 100%
rename from src/usersim/engine/probes/general_educational/assets/general_educational/subjects/hi_Deva_IN/subjects.json
rename to src/usersim/engine/probes/general_educational/assets/general_educational/hi_Deva_IN/subjects.json
diff --git a/src/usersim/engine/probes/general_educational/assets/general_educational/subjects/hi_Latn_IN/subjects.json b/src/usersim/engine/probes/general_educational/assets/general_educational/hi_Latn_IN/subjects.json
similarity index 100%
rename from src/usersim/engine/probes/general_educational/assets/general_educational/subjects/hi_Latn_IN/subjects.json
rename to src/usersim/engine/probes/general_educational/assets/general_educational/hi_Latn_IN/subjects.json
diff --git a/src/usersim/engine/probes/general_educational/assets/general_educational/subjects/ja_JP/subjects.json b/src/usersim/engine/probes/general_educational/assets/general_educational/ja_JP/subjects.json
similarity index 100%
rename from src/usersim/engine/probes/general_educational/assets/general_educational/subjects/ja_JP/subjects.json
rename to src/usersim/engine/probes/general_educational/assets/general_educational/ja_JP/subjects.json
diff --git a/src/usersim/engine/probes/general_educational/assets/general_educational/subjects/ko_KR/subjects.json b/src/usersim/engine/probes/general_educational/assets/general_educational/ko_KR/subjects.json
similarity index 100%
rename from src/usersim/engine/probes/general_educational/assets/general_educational/subjects/ko_KR/subjects.json
rename to src/usersim/engine/probes/general_educational/assets/general_educational/ko_KR/subjects.json
diff --git a/src/usersim/engine/probes/general_educational/assets/general_educational/subjects/pt_BR/subjects.json b/src/usersim/engine/probes/general_educational/assets/general_educational/pt_BR/subjects.json
similarity index 100%
rename from src/usersim/engine/probes/general_educational/assets/general_educational/subjects/pt_BR/subjects.json
rename to src/usersim/engine/probes/general_educational/assets/general_educational/pt_BR/subjects.json
diff --git a/src/usersim/engine/probes/general_educational/probe.py b/src/usersim/engine/probes/general_educational/probe.py
index 9a4130e7..6031c5f2 100644
--- a/src/usersim/engine/probes/general_educational/probe.py
+++ b/src/usersim/engine/probes/general_educational/probe.py
@@ -63,7 +63,7 @@ class EducationalProbe(BaseProbe):
 
     @classmethod
     def themes(cls, locale: str) -> list[dict[str, Any]]:
-        """The subjects in ``locale``'s seed file, or in the base file when the locale has none."""
+        """The subjects in ``locale``'s seed file, or in the ``en_US`` file when the locale has none."""
         return load_seeds(locale, cls.label, "subjects")
 
     @classmethod
diff --git a/src/usersim/engine/probes/general_open_ended/assets/general_open_ended/topics/de_DE/topics.json b/src/usersim/engine/probes/general_open_ended/assets/general_open_ended/de_DE/topics.json
similarity index 100%
rename from src/usersim/engine/probes/general_open_ended/assets/general_open_ended/topics/de_DE/topics.json
rename to src/usersim/engine/probes/general_open_ended/assets/general_open_ended/de_DE/topics.json
diff --git a/src/usersim/engine/probes/general_open_ended/assets/general_open_ended/topics/en_GB/topics.json b/src/usersim/engine/probes/general_open_ended/assets/general_open_ended/en_GB/topics.json
similarity index 100%
rename from src/usersim/engine/probes/general_open_ended/assets/general_open_ended/topics/en_GB/topics.json
rename to src/usersim/engine/probes/general_open_ended/assets/general_open_ended/en_GB/topics.json
diff --git a/src/usersim/engine/probes/general_open_ended/assets/general_open_ended/topics/base/topics.json b/src/usersim/engine/probes/general_open_ended/assets/general_open_ended/en_US/topics.json
similarity index 100%
rename from src/usersim/engine/probes/general_open_ended/assets/general_open_ended/topics/base/topics.json
rename to src/usersim/engine/probes/general_open_ended/assets/general_open_ended/en_US/topics.json
diff --git a/src/usersim/engine/probes/general_open_ended/assets/general_open_ended/topics/fr_FR/topics.json b/src/usersim/engine/probes/general_open_ended/assets/general_open_ended/fr_FR/topics.json
similarity index 100%
rename from src/usersim/engine/probes/general_open_ended/assets/general_open_ended/topics/fr_FR/topics.json
rename to src/usersim/engine/probes/general_open_ended/assets/general_open_ended/fr_FR/topics.json
diff --git a/src/usersim/engine/probes/general_open_ended/assets/general_open_ended/topics/hi_Deva_IN/topics.json b/src/usersim/engine/probes/general_open_ended/assets/general_open_ended/hi_Deva_IN/topics.json
similarity index 100%
rename from src/usersim/engine/probes/general_open_ended/assets/general_open_ended/topics/hi_Deva_IN/topics.json
rename to src/usersim/engine/probes/general_open_ended/assets/general_open_ended/hi_Deva_IN/topics.json
diff --git a/src/usersim/engine/probes/general_open_ended/assets/general_open_ended/topics/hi_Latn_IN/topics.json b/src/usersim/engine/probes/general_open_ended/assets/general_open_ended/hi_Latn_IN/topics.json
similarity index 100%
rename from src/usersim/engine/probes/general_open_ended/assets/general_open_ended/topics/hi_Latn_IN/topics.json
rename to src/usersim/engine/probes/general_open_ended/assets/general_open_ended/hi_Latn_IN/topics.json
diff --git a/src/usersim/engine/probes/general_open_ended/assets/general_open_ended/topics/ja_JP/topics.json b/src/usersim/engine/probes/general_open_ended/assets/general_open_ended/ja_JP/topics.json
similarity index 100%
rename from src/usersim/engine/probes/general_open_ended/assets/general_open_ended/topics/ja_JP/topics.json
rename to src/usersim/engine/probes/general_open_ended/assets/general_open_ended/ja_JP/topics.json
diff --git a/src/usersim/engine/probes/general_open_ended/assets/general_open_ended/topics/ko_KR/topics.json b/src/usersim/engine/probes/general_open_ended/assets/general_open_ended/ko_KR/topics.json
similarity index 100%
rename from src/usersim/engine/probes/general_open_ended/assets/general_open_ended/topics/ko_KR/topics.json
rename to src/usersim/engine/probes/general_open_ended/assets/general_open_ended/ko_KR/topics.json
diff --git a/src/usersim/engine/probes/general_open_ended/assets/general_open_ended/topics/pt_BR/topics.json b/src/usersim/engine/probes/general_open_ended/assets/general_open_ended/pt_BR/topics.json
similarity index 100%
rename from src/usersim/engine/probes/general_open_ended/assets/general_open_ended/topics/pt_BR/topics.json
rename to src/usersim/engine/probes/general_open_ended/assets/general_open_ended/pt_BR/topics.json
diff --git a/src/usersim/engine/probes/general_open_ended/probe.py b/src/usersim/engine/probes/general_open_ended/probe.py
index 4051919d..767ac12e 100644
--- a/src/usersim/engine/probes/general_open_ended/probe.py
+++ b/src/usersim/engine/probes/general_open_ended/probe.py
@@ -62,7 +62,7 @@ class OpenEndedProbe(BaseProbe):
 
     @classmethod
     def themes(cls, locale: str) -> list[dict[str, Any]]:
-        """The topics in ``locale``'s seed file, or in the base file when the locale has none."""
+        """The topics in ``locale``'s seed file, or in the ``en_US`` file when the locale has none."""
         return load_seeds(locale, cls.label, "topics")
 
     @classmethod
diff --git a/tests/engine/core/test_default_asset_paths.py b/tests/engine/core/test_default_asset_paths.py
index 19dd09b1..5add8721 100644
--- a/tests/engine/core/test_default_asset_paths.py
+++ b/tests/engine/core/test_default_asset_paths.py
@@ -158,7 +158,7 @@ def test_seeds_default_path_loads_for_every_locale(
     kind: str,
 ) -> None:
     """``load_seeds`` raises ``FileNotFoundError`` when neither the
-    locale-specific file nor the ``base/`` fallback exists. We assert
+    locale's own file nor the ``en_US`` fallback exists. We assert
     a non-empty result so a bug that ships an empty file (or points at
     one) also fails."""
     seeds = load_seeds(locale, probe, kind)
diff --git a/tests/engine/core/test_multi_locale.py b/tests/engine/core/test_multi_locale.py
index 42a33ac0..f82ce2ba 100644
--- a/tests/engine/core/test_multi_locale.py
+++ b/tests/engine/core/test_multi_locale.py
@@ -9,7 +9,7 @@
 from usersim.engine.core._assets import probe_assets_dir
 from usersim.engine.core.behavioral import LOCALE_LANGUAGE_MAP, get_conversation_language
 from usersim.engine.core.locale import SHIPPED_LOCALES
-from usersim.engine.core.seeds import load_seeds
+from usersim.engine.core.seeds import FALLBACK_LOCALE, load_seeds
 
 LOCALES = SHIPPED_LOCALES
 
@@ -48,26 +48,26 @@ def check_assets(self):
         # Fail rather than skip: the seeds ship with the package, so their
         # absence is a packaging defect, not an environment the test can excuse.
         for probe, kind in [("general_open_ended", "topics"), ("general_educational", "subjects")]:
-            base = probe_assets_dir(probe) / kind / "base"
-            assert base.is_dir(), f"packaged seeds missing at {base}"
+            fallback = probe_assets_dir(probe) / FALLBACK_LOCALE / f"{kind}.json"
+            assert fallback.is_file(), f"packaged seeds missing at {fallback}"
 
-    def test_base_seeds_available_for_all_locales(self):
+    def test_seeds_available_for_all_locales(self):
         for locale in LOCALES:
             topics = load_seeds(locale, "general_open_ended", "topics")
-            assert len(topics) >= 15  # base has 15
+            assert len(topics) >= 15  # ja_JP and ko_KR, the smallest, have 15
 
             subjects = load_seeds(locale, "general_educational", "subjects")
-            assert len(subjects) >= 10  # base has 10
+            assert len(subjects) >= 10  # pt_BR, the smallest, has 10
 
     def test_locale_seed_counts_preserve_localized_replacements(self):
-        base_count = len(load_seeds("en_US", "general_open_ended", "topics"))
+        us_count = len(load_seeds("en_US", "general_open_ended", "topics"))
         pt_count = len(load_seeds("pt_BR", "general_open_ended", "topics"))
-        assert base_count == 48
+        assert us_count == 48
         assert pt_count == 20
 
-        base_ed = len(load_seeds("en_US", "general_educational", "subjects"))
+        us_ed = len(load_seeds("en_US", "general_educational", "subjects"))
         ja_ed = len(load_seeds("ja_JP", "general_educational", "subjects"))
-        assert base_ed == 40
+        assert us_ed == 40
         assert ja_ed == 14
 
     def test_seed_kinds_have_required_fields(self):
diff --git a/tests/engine/core/test_seeds.py b/tests/engine/core/test_seeds.py
index e0df6092..c9af6c97 100644
--- a/tests/engine/core/test_seeds.py
+++ b/tests/engine/core/test_seeds.py
@@ -1,7 +1,7 @@
 # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 
-"""Tests for core/seeds.py — per-probe seed loader with locale fallback."""
+"""Tests for core/seeds.py: the per-probe seed loader and its en_US fallback."""
 
 import json
 from pathlib import Path
@@ -16,36 +16,36 @@ def seed_dir(tmp_path):
     """Build the per-probe layout this loader expects:
 
     tmp_path/
-      general_open_ended/topics/{base,pt_BR}/topics.json
-      general_educational/subjects/base/subjects.json
+      general_open_ended/{en_US,pt_BR}/topics.json
+      general_educational/en_US/subjects.json
     """
-    oe_base = tmp_path / "general_open_ended" / "topics" / "base"
-    oe_base.mkdir(parents=True)
-    base_topics = [
+    oe_us = tmp_path / "general_open_ended" / "en_US"
+    oe_us.mkdir(parents=True)
+    us_topics = [
         {"type": "health", "description": "Health topics"},
         {"type": "finance", "description": "Finance topics"},
     ]
-    (oe_base / "topics.json").write_text(json.dumps(base_topics))
+    (oe_us / "topics.json").write_text(json.dumps(us_topics))
 
-    oe_pt = tmp_path / "general_open_ended" / "topics" / "pt_BR"
+    oe_pt = tmp_path / "general_open_ended" / "pt_BR"
     oe_pt.mkdir(parents=True)
     pt_topics = [{"type": "sus", "description": "SUS healthcare"}]
     (oe_pt / "topics.json").write_text(json.dumps(pt_topics))
 
-    ed_base = tmp_path / "general_educational" / "subjects" / "base"
-    ed_base.mkdir(parents=True)
-    (ed_base / "subjects.json").write_text(json.dumps([{"type": "math", "description": "Mathematics"}]))
+    ed_us = tmp_path / "general_educational" / "en_US"
+    ed_us.mkdir(parents=True)
+    (ed_us / "subjects.json").write_text(json.dumps([{"type": "math", "description": "Mathematics"}]))
 
     return tmp_path
 
 
 class TestLoadSeeds:
-    def test_loads_base_only(self, seed_dir: Path) -> None:
+    def test_en_us_reads_its_own_file(self, seed_dir: Path) -> None:
         seeds = load_seeds("en_US", "general_open_ended", "topics", seed_dir)
         assert len(seeds) == 2
         assert seeds[0]["type"] == "health"
 
-    def test_locale_replaces_base(self, seed_dir: Path) -> None:
+    def test_a_locale_file_replaces_the_en_us_one(self, seed_dir: Path) -> None:
         seeds = load_seeds("pt_BR", "general_open_ended", "topics", seed_dir)
         assert len(seeds) == 1
         assert seeds[0]["type"] == "sus"
@@ -58,9 +58,9 @@ def test_missing_probe_raises(self, seed_dir: Path) -> None:
         with pytest.raises(FileNotFoundError):
             load_seeds("en_US", "no_such_probe", "topics", seed_dir)
 
-    def test_locale_without_translation_falls_back_to_base(self, seed_dir: Path) -> None:
+    def test_a_locale_without_a_file_reads_the_en_us_one(self, seed_dir: Path) -> None:
         seeds = load_seeds("ja_JP", "general_open_ended", "topics", seed_dir)
-        assert len(seeds) == 2
+        assert [s["type"] for s in seeds] == ["health", "finance"]
 
     def test_educational_kind_loads(self, seed_dir: Path) -> None:
         seeds = load_seeds("en_US", "general_educational", "subjects", seed_dir)