diff --git a/.env.example b/.env.example
index 68490c6b..eb60feab 100644
--- a/.env.example
+++ b/.env.example
@@ -1,58 +1,14 @@
-# Database
+# Only SM_DATABASE_URL is required. Everything else has sensible defaults.
+# All module-level settings (SMTP, Celery, users, etc.) are now managed in
+# the admin UI at /settings/modules — no env vars needed.
+
+# Database (required)
 SM_DATABASE_URL=sqlite+aiosqlite:///./app.db
 # SM_DATABASE_URL=postgresql+asyncpg://sm:sm@localhost:5432/simple_module
 
-# App
+# Process identity (production must override SM_SECRET_KEY)
 SM_ENVIRONMENT=development
 SM_SECRET_KEY=change-me-in-production
-SM_VITE_DEV_URL=http://localhost:5050
-
-# Users module — local email+password auth (replaces Keycloak)
-#
-# Signup mode: false = admin-invite only (default), true = public signup
-SM_USERS_ALLOW_SIGNUP=false
-
-# Token secrets — MUST change in production. Dev placeholders are visible in
-# log lines so they're obvious to rotate.
-SM_USERS_RESET_PASSWORD_TOKEN_SECRET=dev-reset-token-secret-change-me
-SM_USERS_VERIFICATION_TOKEN_SECRET=dev-verify-token-secret-change-me
-
-# Mailer: console (logs tokenized links at INFO) or smtp
-SM_USERS_MAILER=console
-SM_USERS_BASE_URL=http://localhost:8000
-# SM_USERS_SMTP_HOST=
-# SM_USERS_SMTP_PORT=587
-# SM_USERS_SMTP_USERNAME=
-# SM_USERS_SMTP_PASSWORD=
-# SM_USERS_SMTP_FROM=no-reply@localhost
-# SM_USERS_SMTP_TLS=true
 
-# First-admin bootstrap (auto-create an admin on first boot iff users table
-# is empty AND both are set). Leave blank to disable — use `sm-users
-# create-admin` instead.
-# SM_USERS_BOOTSTRAP_EMAIL=admin@example.com
-# SM_USERS_BOOTSTRAP_PASSWORD=changeme
-
-# Optional second seeded user with the "user" role. Seeded alongside the
-# admin on first boot (same empty-table guard). When both env vars are set
-# AND SM_ENVIRONMENT=development, the login page renders quick-login buttons
-# for both accounts to speed up manual testing. Leave blank in production.
-# SM_USERS_BOOTSTRAP_USER_EMAIL=user@example.com
-# SM_USERS_BOOTSTRAP_USER_PASSWORD=changeme
-
-# Cookie: set cookie_secure=false in dev (HTTPS-only otherwise)
-SM_USERS_COOKIE_SECURE=false
-
-# Multi-tenancy (default off).
-# SM_MULTI_TENANT=false
-# SM_TENANT_HEADER=
-
-# BackgroundTasks module — Celery + Redis task queue.
-# In docker-compose these point at the `redis` service host (redis://redis:6379/*).
-SM_BG_TASKS_BROKER_URL=redis://localhost:6379/0
-SM_BG_TASKS_RESULT_BACKEND=redis://localhost:6379/1
-# How long a task can stay in `running` without a heartbeat before it's
-# flipped to `stuck` by the beat sweep.
-SM_BG_TASKS_STUCK_AFTER_SECONDS=300
-# Purge terminal rows older than this (days) — keeps history bounded.
-SM_BG_TASKS_RETENTION_DAYS=14
+# Dev-only: Vite asset URL (ignored in production builds)
+SM_VITE_DEV_URL=http://localhost:5050
diff --git a/.gitignore b/.gitignore
index 5bca149a..6c612b0b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -56,3 +56,4 @@ Thumbs.db
 .playwright-cli/*
 .playwright-mcp/*
 host/client_app/.playwright-cli/*
+.superpowers/
diff --git a/README.md b/README.md
index 13af19eb..76dceb68 100644
--- a/README.md
+++ b/README.md
@@ -89,21 +89,26 @@ docs/
 
 ## Configuration
 
-All settings are `SM_`-prefixed env vars. Defaults in `.env.example` cover local dev. Key knobs:
+Local deployments only need one env var — everything else has sensible defaults and is managed in the admin UI at `/settings/modules`.
 
-| Variable | Default | Notes |
+| Variable | Default | Required |
 |---|---|---|
-| `SM_DATABASE_URL` | `sqlite+aiosqlite:///./app.db` | Async URL. Postgres: `postgresql+asyncpg://...` |
-| `SM_ENVIRONMENT` | `development` | Anything else triggers strict module discovery |
-| `SM_SECRET_KEY` | _(placeholder)_ | **Must** change in production — signs session cookies |
-| `SM_USERS_ALLOW_SIGNUP` | `false` | Enable public signup (else admin-invite only) |
-| `SM_USERS_MAILER` | `console` | `console` logs links; `smtp` uses SMTP config (see `.env.example`) |
-| `SM_USERS_RESET_PASSWORD_TOKEN_SECRET` | _(dev placeholder)_ | **Must** change in production |
-| `SM_USERS_VERIFICATION_TOKEN_SECRET` | _(dev placeholder)_ | **Must** change in production |
-| `SM_USERS_BOOTSTRAP_EMAIL` | `` | First-admin email; combined with `SM_USERS_BOOTSTRAP_PASSWORD`, creates admin on first boot iff users table is empty |
-| `SM_USERS_BOOTSTRAP_PASSWORD` | `` | Paired with above |
-| `SM_MULTI_TENANT` | `false` | Set `true` to enable `TenantMiddleware` |
-| `SM_TENANT_HEADER` | `` | Empty = token-only; set e.g. `X-Tenant-ID` to enable header fallback |
+| `SM_DATABASE_URL` | `sqlite+aiosqlite:///./app.db` | Yes — async URL. Postgres: `postgresql+asyncpg://...` |
+| `SM_ENVIRONMENT` | `development` | No — any value other than `development`, `test`, `testing` triggers strict discovery and placeholder-secret checks |
+| `SM_SECRET_KEY` | `change-me-in-production` | No in dev; **must** be overridden in production |
+| `SM_VITE_DEV_URL` | `http://localhost:5050` | Dev only |
+
+Power users can still override the following bootstrap knobs via env if needed: `SM_DB_POOL_SIZE`, `SM_DB_MAX_OVERFLOW`, `SM_DB_POOL_PRE_PING`, `SM_DB_POOL_RECYCLE`, `SM_DEBUG`, `SM_LOG_LEVEL`, `SM_LOG_FORMAT`, `SM_MODULES_ENABLED`. These are needed before the DB connection is open.
+
+All module-level settings — users, SMTP, Celery broker, file storage backend, etc. — live in the admin UI. After upgrading an existing deployment, run once:
+
+```bash
+uv run sm-settings import-from-env
+```
+
+to seed DB overrides from the current `SM_*` environment.
+
+> **docker-compose note:** `docker-compose.yml` sets a few `SM_BG_TASKS_*` vars so Celery can reach the `redis` service by container hostname before the DB-backed settings are loaded. That's deployment plumbing — not a module config knob.
 
 See `framework-conventions.md` for the settings-per-module convention.
 
diff --git a/docs/release-notes/2026-04-21-db-backed-settings.md b/docs/release-notes/2026-04-21-db-backed-settings.md
new file mode 100644
index 00000000..2ead4b90
--- /dev/null
+++ b/docs/release-notes/2026-04-21-db-backed-settings.md
@@ -0,0 +1,15 @@
+# DB-backed module settings
+
+Every `SM_<MODULE>_*` env var has moved to the admin UI at `/settings/modules`.
+`.env` now only needs `SM_DATABASE_URL` in typical deployments.
+
+## Upgrading
+
+After deploying this release:
+
+1. Run `uv run sm-settings import-from-env` once to seed the DB with your current environment values.
+2. Remove the `SM_<MODULE>_*` entries from your `.env` / deployment config (they're no longer read).
+
+## Breaking changes
+
+Setting `SM_USERS_ALLOW_SIGNUP=true` (or any other `SM_<MODULE>_*`) in the environment no longer has any effect. Use the admin UI or the `sm-settings` CLI.
diff --git a/docs/superpowers/plans/2026-04-21-db-backed-module-settings.md b/docs/superpowers/plans/2026-04-21-db-backed-module-settings.md
new file mode 100644
index 00000000..6b595e25
--- /dev/null
+++ b/docs/superpowers/plans/2026-04-21-db-backed-module-settings.md
@@ -0,0 +1,2874 @@
+# DB-backed Module Settings Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Replace `SM_<MODULE>_*` env-var sprawl with DB-backed overrides behind every module's pydantic `BaseSettings`, plus a typed admin UI at `/settings/modules` that supports hot-reload and per-field "Requires restart" semantics.
+
+**Architecture:** Pydantic `BaseSettings` classes become pure schemas (no env reading). A new `ModuleSettingsRegistry` tracks `{package: BaseSettings_cls}`. A framework-level hydration step, run at the start of the FastAPI lifespan before any module `on_startup`, resolves each module's effective settings from `DB value > pydantic default` and reassigns `app.state.<package>.settings`. UI saves hit a new API that validates (by constructing the `BaseSettings`), writes deltas to the existing `Setting` table under `scope="system"`, reassigns `app.state`, and publishes a `SettingsReloaded` event. Host-level env is reduced to a small bootstrap group; power users can still set rarely-touched host knobs via env too.
+
+**Tech Stack:** Python 3.12, FastAPI, pydantic v2, pydantic-settings, SQLModel, SQLAlchemy async, Inertia.js, React 18, Tailwind 4, Vite.
+
+**Spec:** [docs/superpowers/specs/2026-04-21-db-backed-module-settings-design.md](../specs/2026-04-21-db-backed-module-settings-design.md)
+
+---
+
+## Phase 0: Safety net
+
+### Task 0.1: Verify clean baseline
+
+**Files:** none
+
+- [ ] **Step 1: Run the full test suite to confirm the starting point is green**
+
+Run: `make test`
+Expected: PASS (both `test-py` and `test-js`).
+
+- [ ] **Step 2: Run lint**
+
+Run: `make lint`
+Expected: PASS.
+
+- [ ] **Step 3: Run doctor**
+
+Run: `make doctor`
+Expected: PASS.
+
+If any of these fail, stop and fix the existing breakage before proceeding — subsequent tasks assume a green baseline.
+
+---
+
+## Phase 1: Framework plumbing — registry, hydrator, store
+
+All work lives in `modules/settings/settings/` so the Settings module owns the DB-backed config mechanism.
+
+### Task 1.1: Add `ModuleSettingsRegistry`
+
+**Files:**
+- Create: `modules/settings/settings/module_registry.py`
+- Test: `modules/settings/tests/test_module_registry.py`
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+# modules/settings/tests/test_module_registry.py
+"""Tests for ModuleSettingsRegistry — tracks {package: BaseSettings_cls}."""
+
+from __future__ import annotations
+
+import pytest
+from pydantic_settings import BaseSettings
+
+from settings.module_registry import ModuleSettingsRegistry
+
+
+class _Foo(BaseSettings):
+    x: int = 7
+
+
+class _Bar(BaseSettings):
+    y: str = "z"
+
+
+def test_register_and_get() -> None:
+    r = ModuleSettingsRegistry()
+    r.register("foo", _Foo)
+    assert r.get("foo") is _Foo
+
+
+def test_register_duplicate_raises() -> None:
+    r = ModuleSettingsRegistry()
+    r.register("foo", _Foo)
+    with pytest.raises(ValueError, match="already registered"):
+        r.register("foo", _Foo)
+
+
+def test_all_packages_sorted() -> None:
+    r = ModuleSettingsRegistry()
+    r.register("bar", _Bar)
+    r.register("foo", _Foo)
+    assert r.all_packages() == ["bar", "foo"]
+
+
+def test_get_missing_returns_none() -> None:
+    assert ModuleSettingsRegistry().get("nope") is None
+```
+
+- [ ] **Step 2: Run the test and confirm it fails**
+
+Run: `uv run pytest modules/settings/tests/test_module_registry.py -v`
+Expected: FAIL — `ModuleNotFoundError: No module named 'settings.module_registry'`.
+
+- [ ] **Step 3: Implement the registry**
+
+```python
+# modules/settings/settings/module_registry.py
+"""Registry of per-module pydantic BaseSettings classes.
+
+Populated during each module's ``register_settings`` via
+``register_module_settings``. The hosting lifespan reads this at startup
+to hydrate every module's effective settings from the DB.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from pydantic_settings import BaseSettings
+
+
+@dataclass(slots=True)
+class ModuleSettingsRegistry:
+    """In-memory map of ``package`` → ``BaseSettings`` subclass."""
+
+    _classes: dict[str, type[BaseSettings]] = field(default_factory=dict)
+
+    def register(self, package: str, cls: type[BaseSettings]) -> None:
+        if package in self._classes:
+            raise ValueError(f"{package!r} already registered")
+        self._classes[package] = cls
+
+    def get(self, package: str) -> type[BaseSettings] | None:
+        return self._classes.get(package)
+
+    def all_packages(self) -> list[str]:
+        return sorted(self._classes)
+
+    def items(self) -> list[tuple[str, type[BaseSettings]]]:
+        return sorted(self._classes.items())
+```
+
+- [ ] **Step 4: Run the test and confirm it passes**
+
+Run: `uv run pytest modules/settings/tests/test_module_registry.py -v`
+Expected: 4 passed.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add modules/settings/settings/module_registry.py modules/settings/tests/test_module_registry.py
+git commit -m "feat(settings): add ModuleSettingsRegistry for per-module BaseSettings classes"
+```
+
+---
+
+### Task 1.2: Add `SettingsStore` — namespaced k/v over `Setting` table
+
+**Files:**
+- Create: `modules/settings/settings/store.py`
+- Test: `modules/settings/tests/test_store.py`
+
+The store uses the existing `Setting` table with `scope="system"`, `scope_id="system"`, and `key="<package>.<field>"`.
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+# modules/settings/tests/test_store.py
+"""Round-trip tests for SettingsStore — namespaced k/v over the Setting table."""
+
+from __future__ import annotations
+
+import pytest
+
+from settings.service import SettingService
+from settings.store import SettingsStore
+
+
+@pytest.mark.asyncio
+async def test_set_and_get_overrides(db_session) -> None:
+    store = SettingsStore(SettingService(db_session))
+    await store.set_override("users", "allow_signup", "true", "bool")
+    await store.set_override("users", "smtp_port", "587", "int")
+    await store.set_override("background_tasks", "retention_days", "30", "int")
+
+    users = await store.get_overrides("users")
+    assert users == {
+        "allow_signup": ("true", "bool"),
+        "smtp_port": ("587", "int"),
+    }
+    bg = await store.get_overrides("background_tasks")
+    assert bg == {"retention_days": ("30", "int")}
+
+
+@pytest.mark.asyncio
+async def test_set_override_updates_existing(db_session) -> None:
+    store = SettingsStore(SettingService(db_session))
+    await store.set_override("users", "allow_signup", "true", "bool")
+    await store.set_override("users", "allow_signup", "false", "bool")
+
+    assert await store.get_overrides("users") == {"allow_signup": ("false", "bool")}
+
+
+@pytest.mark.asyncio
+async def test_clear_override(db_session) -> None:
+    store = SettingsStore(SettingService(db_session))
+    await store.set_override("users", "allow_signup", "true", "bool")
+    await store.clear_override("users", "allow_signup")
+
+    assert await store.get_overrides("users") == {}
+
+
+@pytest.mark.asyncio
+async def test_clear_override_missing_is_noop(db_session) -> None:
+    store = SettingsStore(SettingService(db_session))
+    await store.clear_override("users", "does_not_exist")  # must not raise
+
+
+@pytest.mark.asyncio
+async def test_list_packages_with_overrides(db_session) -> None:
+    store = SettingsStore(SettingService(db_session))
+    await store.set_override("users", "allow_signup", "true", "bool")
+    await store.set_override("background_tasks", "retention_days", "7", "int")
+
+    assert await store.list_packages_with_overrides() == ["background_tasks", "users"]
+```
+
+- [ ] **Step 2: Run and confirm failure**
+
+Run: `uv run pytest modules/settings/tests/test_store.py -v`
+Expected: FAIL — `ModuleNotFoundError: No module named 'settings.store'`.
+
+- [ ] **Step 3: Implement the store**
+
+```python
+# modules/settings/settings/store.py
+"""DB-backed key/value store for module settings (SYSTEM scope).
+
+Wraps the existing SettingService. Keys are namespaced ``<package>.<field>``
+to avoid collision with free-form user-defined setting keys.
+"""
+
+from __future__ import annotations
+
+from settings.constants import SCOPE_SYSTEM, SYSTEM_SCOPE_ID
+from settings.contracts.schemas import SettingScope, SettingUpsert, SettingValueType
+from settings.service import SettingService
+
+
+def _key(package: str, field: str) -> str:
+    return f"{package}.{field}"
+
+
+class SettingsStore:
+    """SYSTEM-scoped key/value store keyed by ``(package, field)``."""
+
+    def __init__(self, service: SettingService) -> None:
+        self._service = service
+
+    async def get_overrides(self, package: str) -> dict[str, tuple[str, str]]:
+        """Return ``{field_name: (raw_value, value_type)}`` for a package."""
+        prefix = f"{package}."
+        items = await self._service.list_by_scope(SettingScope.SYSTEM, SYSTEM_SCOPE_ID)
+        out: dict[str, tuple[str, str]] = {}
+        for item in items:
+            if not item.key.startswith(prefix):
+                continue
+            field_name = item.key[len(prefix):]
+            # Skip nested keys — namespaces are flat for module settings.
+            if "." in field_name:
+                continue
+            out[field_name] = (item.value, item.value_type)
+        return out
+
+    async def set_override(
+        self, package: str, field: str, value: str, value_type: str
+    ) -> None:
+        await self._service.upsert_scoped(
+            SettingScope.SYSTEM,
+            SYSTEM_SCOPE_ID,
+            _key(package, field),
+            SettingUpsert(value=value, value_type=SettingValueType(value_type)),
+        )
+
+    async def clear_override(self, package: str, field: str) -> None:
+        await self._service.delete_scoped(
+            SettingScope.SYSTEM, SYSTEM_SCOPE_ID, _key(package, field)
+        )
+
+    async def list_packages_with_overrides(self) -> list[str]:
+        items = await self._service.list_by_scope(SettingScope.SYSTEM, SYSTEM_SCOPE_ID)
+        pkgs: set[str] = set()
+        for item in items:
+            if "." not in item.key:
+                continue
+            pkg, rest = item.key.split(".", 1)
+            if "." in rest:
+                continue  # ignore deeper nests
+            pkgs.add(pkg)
+        return sorted(pkgs)
+```
+
+If `SettingValueType` does not already exist as an enum that accepts the string, verify `modules/settings/settings/contracts/schemas.py` exposes it. If not, add it in Task 1.3 before proceeding.
+
+- [ ] **Step 4: Run and confirm pass**
+
+Run: `uv run pytest modules/settings/tests/test_store.py -v`
+Expected: 5 passed.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add modules/settings/settings/store.py modules/settings/tests/test_store.py
+git commit -m "feat(settings): add SettingsStore for module-namespaced overrides"
+```
+
+---
+
+### Task 1.3: Extend `SettingValueType` / `SettingScope` enums if missing
+
+**Files:**
+- Modify: `modules/settings/settings/contracts/schemas.py` (if needed)
+
+- [ ] **Step 1: Verify `SettingValueType` and `SettingScope` exist**
+
+Run: `uv run python -c "from settings.contracts.schemas import SettingValueType, SettingScope; print(list(SettingValueType))"`
+Expected: Prints the enum members. If ImportError, add the enum.
+
+- [ ] **Step 2: If needed, add the missing enum members to match `constants.VALUE_TYPE_*`**
+
+Ensure `SettingValueType` has exactly: `STRING="string"`, `BOOL="bool"`, `INT="int"`, `FLOAT="float"`, `JSON="json"`. Add any missing.
+
+- [ ] **Step 3: Rerun Task 1.2 tests to confirm they still pass**
+
+Run: `uv run pytest modules/settings/tests/test_store.py -v`
+Expected: 5 passed.
+
+- [ ] **Step 4: Commit if any changes were made**
+
+```bash
+git add modules/settings/settings/contracts/schemas.py
+git commit -m "chore(settings): ensure SettingValueType covers all stored value types" || true
+```
+
+---
+
+### Task 1.4: Hydrator — parse DB overrides into a `BaseSettings` instance
+
+**Files:**
+- Create: `modules/settings/settings/hydrate.py`
+- Test: `modules/settings/tests/test_hydrate.py`
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+# modules/settings/tests/test_hydrate.py
+"""Tests for hydrate_settings — resolve DB overrides into a BaseSettings instance."""
+
+from __future__ import annotations
+
+import pytest
+from pydantic import ValidationError
+from pydantic_settings import BaseSettings
+
+from settings.hydrate import hydrate_settings, value_type_for_field
+from settings.service import SettingService
+from settings.store import SettingsStore
+
+
+class _Cfg(BaseSettings):
+    allow: bool = False
+    port: int = 25
+    host: str = "localhost"
+    tags: list[str] = ["a"]
+    rate: float = 1.5
+
+
+@pytest.mark.asyncio
+async def test_hydrate_returns_defaults_when_no_overrides(db_session) -> None:
+    store = SettingsStore(SettingService(db_session))
+    cfg = await hydrate_settings(_Cfg, store, package="demo")
+    assert cfg == _Cfg()
+
+
+@pytest.mark.asyncio
+async def test_hydrate_applies_scalar_overrides(db_session) -> None:
+    store = SettingsStore(SettingService(db_session))
+    await store.set_override("demo", "allow", "true", "bool")
+    await store.set_override("demo", "port", "587", "int")
+    await store.set_override("demo", "host", "mail.example.com", "string")
+    await store.set_override("demo", "rate", "2.5", "float")
+
+    cfg = await hydrate_settings(_Cfg, store, package="demo")
+    assert cfg.allow is True
+    assert cfg.port == 587
+    assert cfg.host == "mail.example.com"
+    assert cfg.rate == 2.5
+
+
+@pytest.mark.asyncio
+async def test_hydrate_applies_json_list_override(db_session) -> None:
+    store = SettingsStore(SettingService(db_session))
+    await store.set_override("demo", "tags", '["x","y","z"]', "json")
+    cfg = await hydrate_settings(_Cfg, store, package="demo")
+    assert cfg.tags == ["x", "y", "z"]
+
+
+@pytest.mark.asyncio
+async def test_hydrate_raises_on_pydantic_validation_error(db_session) -> None:
+    store = SettingsStore(SettingService(db_session))
+    await store.set_override("demo", "port", "not-an-int", "int")
+    with pytest.raises(ValidationError):
+        await hydrate_settings(_Cfg, store, package="demo")
+
+
+def test_value_type_for_bool_int_float_str_list() -> None:
+    assert value_type_for_field(_Cfg, "allow") == "bool"
+    assert value_type_for_field(_Cfg, "port") == "int"
+    assert value_type_for_field(_Cfg, "rate") == "float"
+    assert value_type_for_field(_Cfg, "host") == "string"
+    assert value_type_for_field(_Cfg, "tags") == "json"
+```
+
+- [ ] **Step 2: Run and confirm failure**
+
+Run: `uv run pytest modules/settings/tests/test_hydrate.py -v`
+Expected: FAIL — `ModuleNotFoundError: No module named 'settings.hydrate'`.
+
+- [ ] **Step 3: Implement the hydrator**
+
+```python
+# modules/settings/settings/hydrate.py
+"""Resolve a module's BaseSettings from DB overrides + pydantic defaults.
+
+A field's declared Python type maps to one of the five ``value_type`` labels
+understood by SettingsStore (``string | bool | int | float | json``). The
+hydrator reads overrides, parses each according to its stored ``value_type``,
+and constructs the BaseSettings — pydantic enforces field validators and any
+``@model_validator`` hooks.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import TypeVar, get_args, get_origin
+
+from pydantic_settings import BaseSettings
+
+from settings.store import SettingsStore
+
+T = TypeVar("T", bound=BaseSettings)
+
+
+def value_type_for_field(cls: type[BaseSettings], field_name: str) -> str:
+    """Return the ``value_type`` label for a field based on its annotation.
+
+    - ``bool`` → ``"bool"``
+    - ``int`` → ``"int"``
+    - ``float`` → ``"float"``
+    - ``str`` and enums → ``"string"``
+    - ``list``, ``dict``, and other container types → ``"json"``
+    """
+    info = cls.model_fields[field_name]
+    ann = info.annotation
+    origin = get_origin(ann)
+    if origin is not None:
+        # list[...], dict[...], list[...] | None, etc. → json
+        return "json"
+    if ann is bool:
+        return "bool"
+    if ann is int:
+        return "int"
+    if ann is float:
+        return "float"
+    # str, Literal[...], enum classes, and anything else scalar → string
+    return "string"
+
+
+def _parse(raw: str, value_type: str):  # noqa: ANN202 (pydantic accepts Any)
+    if value_type == "bool":
+        return raw.lower() in ("1", "true", "yes", "on")
+    if value_type == "int":
+        return int(raw)
+    if value_type == "float":
+        return float(raw)
+    if value_type == "json":
+        return json.loads(raw)
+    return raw
+
+
+async def hydrate_settings(cls: type[T], store: SettingsStore, package: str) -> T:
+    """Construct ``cls`` with DB overrides merged over pydantic defaults."""
+    raw_overrides = await store.get_overrides(package)
+    parsed: dict[str, object] = {}
+    for field_name, (raw, vtype) in raw_overrides.items():
+        if field_name not in cls.model_fields:
+            continue  # stale field in DB — silently skip; prune-orphans handles it
+        parsed[field_name] = _parse(raw, vtype)
+    return cls(**parsed)  # pydantic runs validators here
+```
+
+Note the `_ = get_args(ann)` is intentionally unused — `get_origin` alone is enough for the current type set. If you're linting unused imports, remove `get_args` from the import.
+
+- [ ] **Step 4: Remove unused import**
+
+```python
+from typing import TypeVar, get_origin
+```
+
+- [ ] **Step 5: Run and confirm pass**
+
+Run: `uv run pytest modules/settings/tests/test_hydrate.py -v`
+Expected: 5 passed.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add modules/settings/settings/hydrate.py modules/settings/tests/test_hydrate.py
+git commit -m "feat(settings): add hydrate_settings and value_type inference"
+```
+
+---
+
+### Task 1.5: `register_module_settings` helper + update `SettingsServices`
+
+Modules currently set `app.state.<package>` in their own `register_settings` hook. This task introduces a helper that (a) constructs defaults, (b) registers the class in the registry, (c) sets `app.state.<package>.settings` so hooks see defaults before the hosting lifespan hydrates them.
+
+**Files:**
+- Modify: `modules/settings/settings/services.py`
+- Create: `modules/settings/settings/registration.py`
+- Test: `modules/settings/tests/test_registration.py`
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+# modules/settings/tests/test_registration.py
+"""Tests for register_module_settings — helper modules call during boot."""
+
+from __future__ import annotations
+
+import pytest
+from fastapi import FastAPI
+from pydantic_settings import BaseSettings
+
+from settings.constants import MODULE_PACKAGE
+from settings.module_registry import ModuleSettingsRegistry
+from settings.registration import register_module_settings
+from settings.services import SettingsServices
+from settings.settings import SettingsSettings
+
+
+class _FakeModuleServices:
+    def __init__(self, settings):
+        self.settings = settings
+
+
+@pytest.fixture
+def app() -> FastAPI:
+    app = FastAPI()
+    app.state.settings = SettingsServices(
+        settings=SettingsSettings(),
+        registry=__import__("settings.contracts.registry", fromlist=["SettingsRegistry"]).SettingsRegistry(),
+        module_registry=ModuleSettingsRegistry(),
+    )
+    return app
+
+
+class _UsersCfg(BaseSettings):
+    allow: bool = False
+    port: int = 25
+
+
+def test_register_installs_defaults_on_app_state(app):
+    register_module_settings(app, "users", _UsersCfg, _FakeModuleServices)
+    assert isinstance(app.state.users, _FakeModuleServices)
+    assert app.state.users.settings == _UsersCfg()
+
+
+def test_register_adds_to_module_registry(app):
+    register_module_settings(app, "users", _UsersCfg, _FakeModuleServices)
+    assert app.state.settings.module_registry.get("users") is _UsersCfg
+
+
+def test_register_duplicate_raises(app):
+    register_module_settings(app, "users", _UsersCfg, _FakeModuleServices)
+    with pytest.raises(ValueError, match="already registered"):
+        register_module_settings(app, "users", _UsersCfg, _FakeModuleServices)
+```
+
+- [ ] **Step 2: Run and confirm failure**
+
+Run: `uv run pytest modules/settings/tests/test_registration.py -v`
+Expected: FAIL — imports or attribute errors.
+
+- [ ] **Step 3: Add `module_registry` to `SettingsServices`**
+
+Modify `modules/settings/settings/services.py`:
+
+```python
+"""Module-scoped state container.
+
+Stored as ``app.state.settings`` by
+:meth:`SettingsModule.register_settings`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from settings.contracts.registry import SettingsRegistry
+from settings.module_registry import ModuleSettingsRegistry
+from settings.settings import SettingsSettings
+
+
+@dataclass
+class SettingsServices:
+    """Settings module singletons."""
+
+    settings: SettingsSettings
+    registry: SettingsRegistry = field(default_factory=SettingsRegistry)
+    module_registry: ModuleSettingsRegistry = field(default_factory=ModuleSettingsRegistry)
+```
+
+- [ ] **Step 4: Implement `register_module_settings`**
+
+```python
+# modules/settings/settings/registration.py
+"""Helper modules call from ``register_settings`` to install their BaseSettings.
+
+Two things happen:
+1. A fresh ``BaseSettings`` (pydantic defaults only) is constructed.
+2. The class is recorded in ``app.state.settings.module_registry`` so the
+   hosting lifespan can hydrate it from the DB before module ``on_startup``
+   hooks run.
+
+The module's services dataclass is built from the default settings object and
+attached at ``app.state.<package>``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from fastapi import FastAPI
+from pydantic_settings import BaseSettings
+
+from settings.constants import MODULE_PACKAGE
+
+
+def register_module_settings(
+    app: FastAPI,
+    package: str,
+    settings_cls: type[BaseSettings],
+    services_factory: Callable[[BaseSettings], Any],
+) -> None:
+    """Register a module's BaseSettings class and mount its services on app.state.
+
+    Args:
+        app: The FastAPI app being built.
+        package: The module's top-level package name (e.g. ``"users"``).
+        settings_cls: The module's ``BaseSettings`` subclass.
+        services_factory: Callable ``(settings) -> services_dataclass`` used to
+            build the object stored at ``app.state.<package>``. Typically the
+            module's own ``Services`` dataclass constructor.
+    """
+    registry = getattr(app.state, MODULE_PACKAGE).module_registry
+    registry.register(package, settings_cls)
+    defaults = settings_cls()
+    setattr(app.state, package, services_factory(defaults))
+```
+
+- [ ] **Step 5: Run and confirm pass**
+
+Run: `uv run pytest modules/settings/tests/test_registration.py -v`
+Expected: 3 passed.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add modules/settings/settings/services.py modules/settings/settings/registration.py modules/settings/tests/test_registration.py
+git commit -m "feat(settings): add register_module_settings helper + ModuleSettingsRegistry on SettingsServices"
+```
+
+---
+
+### Task 1.6: `SettingsReloaded` event
+
+**Files:**
+- Create: `modules/settings/settings/contracts/events.py`
+- Test: `modules/settings/tests/test_events.py`
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+# modules/settings/tests/test_events.py
+from __future__ import annotations
+
+import pytest
+from simple_module_core.events import EventBus
+
+from settings.contracts.events import SettingsReloaded
+
+
+@pytest.mark.asyncio
+async def test_publish_and_subscribe() -> None:
+    bus = EventBus()
+    received: list[SettingsReloaded] = []
+
+    async def handler(evt: SettingsReloaded) -> None:
+        received.append(evt)
+
+    bus.subscribe(SettingsReloaded, handler)
+    await bus.publish(SettingsReloaded(package="users", changed=("allow_signup",)))
+    assert received == [SettingsReloaded(package="users", changed=("allow_signup",))]
+```
+
+- [ ] **Step 2: Run and confirm failure**
+
+Run: `uv run pytest modules/settings/tests/test_events.py -v`
+Expected: FAIL — ImportError.
+
+- [ ] **Step 3: Implement the event**
+
+```python
+# modules/settings/settings/contracts/events.py
+"""Domain events published by the Settings module."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from simple_module_core.events import Event
+
+
+@dataclass(frozen=True)
+class SettingsReloaded(Event):
+    """Fired after a module's BaseSettings has been reloaded from the DB.
+
+    Subscribers that cached stateful handles built from settings (SMTP client,
+    Celery app config, middleware) can rebuild when ``package`` matches their
+    own.
+    """
+
+    package: str
+    changed: tuple[str, ...]
+```
+
+- [ ] **Step 4: Run and confirm pass**
+
+Run: `uv run pytest modules/settings/tests/test_events.py -v`
+Expected: 1 passed.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add modules/settings/settings/contracts/events.py modules/settings/tests/test_events.py
+git commit -m "feat(settings): add SettingsReloaded event"
+```
+
+---
+
+### Task 1.7: Hot-reload on save
+
+**Files:**
+- Create: `modules/settings/settings/reload.py`
+- Test: `modules/settings/tests/test_reload.py`
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+# modules/settings/tests/test_reload.py
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import pytest
+from fastapi import FastAPI
+from pydantic import ValidationError
+from pydantic_settings import BaseSettings
+from simple_module_core.events import EventBus
+
+from settings.contracts.events import SettingsReloaded
+from settings.module_registry import ModuleSettingsRegistry
+from settings.registration import register_module_settings
+from settings.reload import apply_changes_and_reload
+from settings.service import SettingService
+from settings.services import SettingsServices
+from settings.settings import SettingsSettings
+from settings.store import SettingsStore
+
+
+class _UsersCfg(BaseSettings):
+    allow_signup: bool = False
+    smtp_port: int = 25
+
+
+@dataclass
+class _UsersServices:
+    settings: _UsersCfg
+
+
+@pytest.fixture
+def app_and_bus(db_session) -> tuple[FastAPI, EventBus]:
+    bus = EventBus()
+    app = FastAPI()
+    app.state.settings = SettingsServices(settings=SettingsSettings())
+    register_module_settings(app, "users", _UsersCfg, lambda s: _UsersServices(settings=s))
+    return app, bus
+
+
+@pytest.mark.asyncio
+async def test_apply_changes_updates_app_state_and_fires_event(app_and_bus, db_session):
+    app, bus = app_and_bus
+    received: list[SettingsReloaded] = []
+
+    async def handler(evt: SettingsReloaded) -> None:
+        received.append(evt)
+
+    bus.subscribe(SettingsReloaded, handler)
+
+    store = SettingsStore(SettingService(db_session))
+    new_settings = await apply_changes_and_reload(
+        app, bus, store, package="users",
+        changes={"allow_signup": True, "smtp_port": 587},
+    )
+
+    assert new_settings.allow_signup is True
+    assert new_settings.smtp_port == 587
+    assert app.state.users.settings is new_settings
+    assert received == [SettingsReloaded(package="users", changed=("allow_signup", "smtp_port"))]
+
+    persisted = await store.get_overrides("users")
+    assert persisted == {"allow_signup": ("True", "bool"), "smtp_port": ("587", "int")}
+
+
+@pytest.mark.asyncio
+async def test_apply_changes_validation_error_rolls_back(app_and_bus, db_session):
+    app, bus = app_and_bus
+    store = SettingsStore(SettingService(db_session))
+
+    original = app.state.users.settings
+
+    with pytest.raises(ValidationError):
+        await apply_changes_and_reload(
+            app, bus, store, package="users",
+            changes={"smtp_port": "not-an-int"},  # fails pydantic int coercion
+        )
+
+    assert app.state.users.settings is original
+    assert await store.get_overrides("users") == {}
+
+
+@pytest.mark.asyncio
+async def test_apply_changes_unknown_package_raises(app_and_bus, db_session):
+    app, bus = app_and_bus
+    store = SettingsStore(SettingService(db_session))
+
+    with pytest.raises(KeyError):
+        await apply_changes_and_reload(
+            app, bus, store, package="unknown", changes={"x": 1},
+        )
+```
+
+- [ ] **Step 2: Run and confirm failure**
+
+Run: `uv run pytest modules/settings/tests/test_reload.py -v`
+Expected: FAIL — ImportError.
+
+- [ ] **Step 3: Implement `apply_changes_and_reload`**
+
+```python
+# modules/settings/settings/reload.py
+"""Apply a set of field changes to a module's settings and reload them.
+
+Steps:
+1. Look up the module's BaseSettings class from the registry.
+2. Merge changes over current DB overrides + defaults to form the candidate.
+3. Construct ``cls(**candidate)`` — pydantic validates.
+4. On success, write each change to the store, reassign ``app.state.<package>.settings``,
+   and publish ``SettingsReloaded``.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from fastapi import FastAPI
+from pydantic_settings import BaseSettings
+from simple_module_core.events import EventBus
+
+from settings.constants import MODULE_PACKAGE
+from settings.contracts.events import SettingsReloaded
+from settings.hydrate import hydrate_settings, value_type_for_field
+from settings.store import SettingsStore
+
+
+def _encode(value: Any, value_type: str) -> str:
+    if value_type == "json":
+        return json.dumps(value)
+    return str(value)
+
+
+async def apply_changes_and_reload(
+    app: FastAPI,
+    bus: EventBus,
+    store: SettingsStore,
+    *,
+    package: str,
+    changes: dict[str, Any],
+) -> BaseSettings:
+    """Validate, persist, hot-swap, and publish ``SettingsReloaded``."""
+    registry = getattr(app.state, MODULE_PACKAGE).module_registry
+    cls = registry.get(package)
+    if cls is None:
+        raise KeyError(f"Unknown settings package: {package!r}")
+
+    # Unknown fields are rejected loudly.
+    unknown = set(changes) - set(cls.model_fields)
+    if unknown:
+        raise KeyError(f"Unknown field(s) for {package!r}: {sorted(unknown)}")
+
+    # Merge over current hydrated state for pydantic validation.
+    current = await hydrate_settings(cls, store, package)
+    merged = current.model_dump()
+    merged.update(changes)
+    validated = cls(**merged)  # raises ValidationError on bad input
+
+    # Persist only the requested fields — everything else stays in DB as-is.
+    for field_name, raw_value in changes.items():
+        vtype = value_type_for_field(cls, field_name)
+        encoded = _encode(raw_value, vtype)
+        await store.set_override(package, field_name, encoded, vtype)
+
+    # Rebuild services object to keep the dataclass shape consistent, replacing
+    # only the .settings attribute.
+    services = getattr(app.state, package)
+    services.settings = validated
+
+    await bus.publish(SettingsReloaded(package=package, changed=tuple(sorted(changes))))
+    return validated
+```
+
+- [ ] **Step 4: Run and confirm pass**
+
+Run: `uv run pytest modules/settings/tests/test_reload.py -v`
+Expected: 3 passed.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add modules/settings/settings/reload.py modules/settings/tests/test_reload.py
+git commit -m "feat(settings): add apply_changes_and_reload with validation + SettingsReloaded event"
+```
+
+---
+
+## Phase 2: Hosting — bootstrap split + hydration in lifespan
+
+### Task 2.1: Split `Settings` into `BootstrapSettings` + `HostSettings`
+
+**Files:**
+- Create: `framework/hosting/simple_module_hosting/bootstrap_settings.py`
+- Create: `framework/hosting/simple_module_hosting/host_settings.py`
+- Modify: `framework/hosting/simple_module_hosting/settings.py`
+- Create: `tests/test_bootstrap_settings.py`
+
+`BootstrapSettings` — env-driven, read before DB. Contains: `database_url`, `db_pool_*`, `environment`, `secret_key`, `vite_dev_url`, `debug`, `log_level`, `log_format`, `modules_enabled`.
+
+`HostSettings` — defaults-only (DB-backed like modules). Contains: `multi_tenant`, `tenant_header`, `i18n_default_locale`, `i18n_supported_locales`, `i18n_cookie_name`.
+
+The public `Settings` name is kept as a facade (combines both) so existing import sites keep working for the duration of Phase 2.
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+# tests/test_bootstrap_settings.py
+from __future__ import annotations
+
+import pytest
+
+from simple_module_hosting.bootstrap_settings import BootstrapSettings
+from simple_module_hosting.host_settings import HostSettings
+
+
+def test_bootstrap_reads_from_env(monkeypatch):
+    monkeypatch.setenv("SM_DATABASE_URL", "sqlite+aiosqlite:///:memory:")
+    monkeypatch.setenv("SM_SECRET_KEY", "x" * 48)
+    monkeypatch.setenv("SM_ENVIRONMENT", "development")
+    bs = BootstrapSettings()
+    assert bs.database_url == "sqlite+aiosqlite:///:memory:"
+    assert bs.secret_key == "x" * 48
+    assert bs.environment == "development"
+
+
+def test_bootstrap_placeholder_secret_blocks_production(monkeypatch):
+    monkeypatch.setenv("SM_ENVIRONMENT", "production")
+    monkeypatch.setenv("SM_SECRET_KEY", "change-me-in-production")
+    with pytest.raises(ValueError, match="SM_SECRET_KEY"):
+        BootstrapSettings()
+
+
+def test_host_settings_ignores_env(monkeypatch):
+    # HostSettings must NOT read env — env-sprawl is what we're removing.
+    monkeypatch.setenv("SM_MULTI_TENANT", "true")
+    hs = HostSettings()
+    assert hs.multi_tenant is False  # default wins; env ignored
+
+
+def test_host_settings_default_locale_must_be_supported():
+    with pytest.raises(ValueError):
+        HostSettings(i18n_default_locale="de", i18n_supported_locales=["en"])
+```
+
+- [ ] **Step 2: Run and confirm failure**
+
+Run: `uv run pytest tests/test_bootstrap_settings.py -v`
+Expected: FAIL — ImportError.
+
+- [ ] **Step 3: Implement `BootstrapSettings`**
+
+```python
+# framework/hosting/simple_module_hosting/bootstrap_settings.py
+"""Env-only settings read before the database is available.
+
+Everything here is needed either to connect to the DB, sign session cookies,
+or configure the Python process (logging, Vite asset URLs, module allowlist).
+These values stay in ``.env`` — all other settings live in the DB.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import model_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from simple_module_core.environments import NON_PROD_ENVIRONMENTS
+
+_PLACEHOLDER_SECRET_KEY = "change-me-in-production"
+
+
+class BootstrapSettings(BaseSettings):
+    """Pre-DB bootstrap environment knobs."""
+
+    model_config = SettingsConfigDict(env_prefix="SM_", env_file=".env", extra="ignore")
+
+    # Database — the only required env value in a typical deployment.
+    database_url: str = "sqlite+aiosqlite:///./app.db"
+    db_pool_size: int = 10
+    db_max_overflow: int = 20
+    db_pool_pre_ping: bool = True
+    db_pool_recycle: int = 1800
+
+    # Process identity
+    environment: str = "development"
+    secret_key: str = _PLACEHOLDER_SECRET_KEY
+    vite_dev_url: str = "http://localhost:5050"
+    debug: bool = False
+
+    # Logging (configured before the DB is touched)
+    log_level: str = "INFO"
+    log_format: Literal["json", "text"] = "json"
+
+    # Module allowlist — resolved before any DB access.
+    modules_enabled: list[str] | None = None
+
+    @property
+    def is_development(self) -> bool:
+        return self.environment == "development"
+
+    @model_validator(mode="after")
+    def _forbid_placeholder_secret_in_production(self) -> "BootstrapSettings":
+        if (
+            self.environment not in NON_PROD_ENVIRONMENTS
+            and self.secret_key == _PLACEHOLDER_SECRET_KEY
+        ):
+            raise ValueError(
+                f"SM_SECRET_KEY must be set to a non-default value when "
+                f"SM_ENVIRONMENT={self.environment!r}. Generate one with "
+                "`python -c 'import secrets; print(secrets.token_urlsafe(48))'`."
+            )
+        return self
+```
+
+- [ ] **Step 4: Implement `HostSettings`**
+
+```python
+# framework/hosting/simple_module_hosting/host_settings.py
+"""Host-level settings stored in the DB (not env).
+
+Registered under ``package="host"`` so the UI shows them alongside module
+settings. The hosting layer still reads these directly from
+``app.state.host.settings``.
+"""
+
+from __future__ import annotations
+
+from pydantic import model_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class HostSettings(BaseSettings):
+    """DB-backed host configuration — defaults live here, overrides in DB."""
+
+    # No env_prefix and no env_file: this class must never read environment.
+    model_config = SettingsConfigDict(extra="ignore")
+
+    # Multi-tenancy
+    multi_tenant: bool = False
+    tenant_header: str = ""
+
+    # Internationalization
+    i18n_default_locale: str = "en"
+    i18n_supported_locales: list[str] = ["en"]
+    i18n_cookie_name: str = "locale"
+
+    @model_validator(mode="after")
+    def _check_default_locale_supported(self) -> "HostSettings":
+        if self.i18n_default_locale not in self.i18n_supported_locales:
+            raise ValueError(
+                f"i18n_default_locale '{self.i18n_default_locale}' is not in "
+                f"i18n_supported_locales {self.i18n_supported_locales}"
+            )
+        return self
+```
+
+- [ ] **Step 5: Update `settings.py` to re-export for backwards-compat during migration**
+
+```python
+# framework/hosting/simple_module_hosting/settings.py
+"""Back-compat shim — prefer BootstrapSettings + HostSettings directly.
+
+During migration, existing code that imports ``Settings`` keeps working by
+combining both classes. Once all call sites have migrated, this shim is
+removed.
+"""
+
+from __future__ import annotations
+
+from simple_module_hosting.bootstrap_settings import BootstrapSettings
+from simple_module_hosting.host_settings import HostSettings
+
+
+class Settings(BootstrapSettings):
+    """Combined bootstrap + host settings for legacy import sites.
+
+    Host-level fields still come from class defaults; the env-driven fields
+    come from BootstrapSettings. New code should import BootstrapSettings and
+    HostSettings separately and read host fields from
+    ``app.state.host.settings``.
+    """
+
+    # Carry the HostSettings fields as defaults for legacy consumers.
+    multi_tenant: bool = HostSettings.model_fields["multi_tenant"].default
+    tenant_header: str = HostSettings.model_fields["tenant_header"].default
+    i18n_default_locale: str = HostSettings.model_fields["i18n_default_locale"].default
+    i18n_supported_locales: list[str] = HostSettings.model_fields["i18n_supported_locales"].default
+    i18n_cookie_name: str = HostSettings.model_fields["i18n_cookie_name"].default
+```
+
+- [ ] **Step 6: Run and confirm pass**
+
+Run: `uv run pytest tests/test_bootstrap_settings.py -v`
+Expected: 4 passed.
+
+- [ ] **Step 7: Run full test suite — most should still pass**
+
+Run: `uv run pytest -x`
+Expected: PASS.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add framework/hosting/simple_module_hosting/bootstrap_settings.py framework/hosting/simple_module_hosting/host_settings.py framework/hosting/simple_module_hosting/settings.py tests/test_bootstrap_settings.py
+git commit -m "feat(hosting): split Settings into BootstrapSettings (env) + HostSettings (DB)"
+```
+
+---
+
+### Task 2.2: Register `HostSettings` as `package="host"`
+
+**Files:**
+- Modify: `framework/hosting/simple_module_hosting/app_builder.py`
+- Test: added to `tests/test_bootstrap_settings.py`
+
+This hooks `HostSettings` into the existing `ModuleSettingsRegistry` so the admin UI lists it alongside modules.
+
+- [ ] **Step 1: Add the failing test to `tests/test_bootstrap_settings.py`**
+
+```python
+# append to tests/test_bootstrap_settings.py
+@pytest.mark.asyncio
+async def test_host_settings_registered_as_host_package(app):
+    registry = app.state.settings.module_registry
+    assert registry.get("host").__name__ == "HostSettings"
+    assert isinstance(app.state.host.settings, __import__(
+        "simple_module_hosting.host_settings", fromlist=["HostSettings"]
+    ).HostSettings)
+```
+
+- [ ] **Step 2: Run and confirm failure**
+
+Run: `uv run pytest tests/test_bootstrap_settings.py::test_host_settings_registered_as_host_package -v`
+Expected: FAIL — no "host" entry.
+
+- [ ] **Step 3: Register host in `create_app`**
+
+Modify `framework/hosting/simple_module_hosting/app_builder.py` after Phase 4 (module settings registration, ~line 172):
+
+```python
+    # ── Phase 4: Module settings ───────────────────────────
+    for mod in modules:
+        mod.register_settings(app)
+
+    # Register host-level settings under package="host" (DB-backed). The
+    # Settings module must already have run register_settings (topo order
+    # should put it early; its meta.depends_on = [] so it's scheduled first
+    # among leaves).
+    from dataclasses import dataclass
+    from simple_module_hosting.host_settings import HostSettings
+    from settings.registration import register_module_settings
+
+    @dataclass
+    class _HostServices:
+        settings: HostSettings
+
+    register_module_settings(app, "host", HostSettings, lambda s: _HostServices(settings=s))
+```
+
+Note: we create the dataclass inline to avoid yet another tiny module. If lint flags it, extract to `framework/hosting/simple_module_hosting/_host_services.py`.
+
+- [ ] **Step 4: Run and confirm pass**
+
+Run: `uv run pytest tests/test_bootstrap_settings.py -v`
+Expected: 5 passed.
+
+- [ ] **Step 5: Run full suite**
+
+Run: `uv run pytest -x`
+Expected: PASS.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add framework/hosting/simple_module_hosting/app_builder.py tests/test_bootstrap_settings.py
+git commit -m "feat(hosting): register HostSettings as package='host' in module registry"
+```
+
+---
+
+### Task 2.3: Hydration step at start of lifespan
+
+**Files:**
+- Modify: `framework/hosting/simple_module_hosting/app_builder.py`
+- Create: `framework/hosting/simple_module_hosting/_hydrate_step.py`
+- Test: `tests/test_hydration_lifespan.py`
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+# tests/test_hydration_lifespan.py
+from __future__ import annotations
+
+import pytest
+from httpx import ASGITransport, AsyncClient
+
+
+@pytest.mark.asyncio
+async def test_lifespan_hydrates_host_settings_from_db(app, db_session):
+    """After lifespan starts, host settings reflect DB overrides, not defaults."""
+    from settings.service import SettingService
+    from settings.store import SettingsStore
+
+    # Seed an override before the lifespan's hydrate step would run.
+    # (In this fixture, lifespan has already started — so we simulate by
+    # writing an override and asking the hydrator to re-run.)
+    store = SettingsStore(SettingService(db_session))
+    await store.set_override("host", "multi_tenant", "true", "bool")
+
+    from simple_module_hosting._hydrate_step import hydrate_all
+    await hydrate_all(app, store)
+
+    assert app.state.host.settings.multi_tenant is True
+```
+
+- [ ] **Step 2: Run and confirm failure**
+
+Run: `uv run pytest tests/test_hydration_lifespan.py -v`
+Expected: FAIL — ImportError.
+
+- [ ] **Step 3: Implement `hydrate_all`**
+
+```python
+# framework/hosting/simple_module_hosting/_hydrate_step.py
+"""Framework-level hydration step run at start of the FastAPI lifespan.
+
+Walks every registered module (including ``host``), hydrates its BaseSettings
+from the DB, and reassigns ``app.state.<package>.settings``. Runs before any
+module ``on_startup`` hook so startup code sees DB-backed values.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from fastapi import FastAPI
+
+from settings.constants import MODULE_PACKAGE
+from settings.hydrate import hydrate_settings
+from settings.store import SettingsStore
+
+logger = logging.getLogger(__name__)
+
+
+async def hydrate_all(app: FastAPI, store: SettingsStore) -> None:
+    """Resolve every registered module's settings from the DB."""
+    registry = getattr(app.state, MODULE_PACKAGE).module_registry
+    for package, cls in registry.items():
+        try:
+            hydrated = await hydrate_settings(cls, store, package)
+        except Exception:
+            # One bad override shouldn't prevent boot — log and keep defaults.
+            logger.exception(
+                "Hydrating %s failed; falling back to defaults", package
+            )
+            continue
+        services = getattr(app.state, package, None)
+        if services is None:
+            logger.warning("app.state.%s missing during hydrate — skipping", package)
+            continue
+        services.settings = hydrated
+```
+
+- [ ] **Step 4: Wire `hydrate_all` into the lifespan**
+
+Modify `framework/hosting/simple_module_hosting/app_builder.py`, replace the lifespan body:
+
+```python
+    @asynccontextmanager
+    async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
+        app.state.migration = await check_migrations(app.state.sm.db.engine)
+
+        # Hydrate all registered settings from DB before any module on_startup.
+        from simple_module_hosting._hydrate_step import hydrate_all
+        from settings.service import SettingService
+        from settings.store import SettingsStore
+
+        async with app.state.sm.db.session_factory() as session:
+            store = SettingsStore(SettingService(session))
+            await hydrate_all(app, store)
+
+        for mod in modules:
+            await mod.on_startup(app)
+        yield
+        for mod in reversed(modules):
+            await mod.on_shutdown(app)
+        await app.state.sm.db.engine.dispose()
+```
+
+Check `app.state.sm.db.session_factory` vs the actual attribute name in `simple_module_db.session`. If it's a different name (e.g. `async_session_maker`), adapt the call.
+
+- [ ] **Step 5: Run the hydration lifespan test**
+
+Run: `uv run pytest tests/test_hydration_lifespan.py -v`
+Expected: PASS.
+
+- [ ] **Step 6: Run full test suite**
+
+Run: `uv run pytest -x`
+Expected: PASS.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add framework/hosting/simple_module_hosting/_hydrate_step.py framework/hosting/simple_module_hosting/app_builder.py tests/test_hydration_lifespan.py
+git commit -m "feat(hosting): hydrate module settings from DB at start of lifespan"
+```
+
+---
+
+## Phase 3: Per-module migration
+
+Each module: (1) drop `env_prefix`/`env_file` from its `SettingsConfigDict`, (2) refactor `register_settings` to use `register_module_settings`, (3) update tests that `monkeypatch.setenv` to use the store instead.
+
+### Task 3.1: Migrate Settings module (itself)
+
+**Files:**
+- Modify: `modules/settings/settings/settings.py`
+- Modify: `modules/settings/settings/module.py`
+
+- [ ] **Step 1: Strip env config from `SettingsSettings`**
+
+```python
+# modules/settings/settings/settings.py
+"""Settings module's own configuration (DB-backed)."""
+
+from __future__ import annotations
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class SettingsSettings(BaseSettings):
+    """Configuration for the Settings module."""
+
+    model_config = SettingsConfigDict(extra="ignore")
+```
+
+- [ ] **Step 2: Use `register_module_settings` in `SettingsModule.register_settings`**
+
+Modify `modules/settings/settings/module.py`:
+
+```python
+    def register_settings(self, app: FastAPI) -> None:
+        # The settings module itself bootstraps its own services object —
+        # it can't use register_module_settings because that helper reads
+        # app.state.settings.module_registry, which doesn't exist yet.
+        from settings.module_registry import ModuleSettingsRegistry
+        from settings.contracts.registry import SettingsRegistry
+        from settings.services import SettingsServices
+        from settings.settings import SettingsSettings
+
+        services = SettingsServices(
+            settings=SettingsSettings(),
+            registry=SettingsRegistry(),
+            module_registry=ModuleSettingsRegistry(),
+        )
+        setattr(app.state, MODULE_PACKAGE, services)
+
+        # Self-register so the UI sees our own settings in the list.
+        services.module_registry.register("settings", SettingsSettings)
+```
+
+- [ ] **Step 3: Run the settings module test suite**
+
+Run: `uv run pytest modules/settings/tests/ -v`
+Expected: PASS.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add modules/settings/settings/settings.py modules/settings/settings/module.py
+git commit -m "refactor(settings): move SettingsSettings off env (DB-backed) and self-register"
+```
+
+---
+
+### Task 3.2: Migrate Users module
+
+**Files:**
+- Modify: `modules/users/users/settings.py`
+- Modify: `modules/users/users/module.py`
+- Modify: `modules/users/tests/test_settings.py`
+
+- [ ] **Step 1: Strip `env_prefix` / `env_file` from `UsersSettings`**
+
+Replace the `SettingsConfigDict` line in `modules/users/users/settings.py`:
+
+```python
+    model_config = SettingsConfigDict(extra="ignore")
+```
+
+Keep the `@model_validator` for placeholder token secrets — it now runs on DB-read (via hydrate).
+
+- [ ] **Step 2: Update the module's `register_settings` to use the helper**
+
+Open `modules/users/users/module.py`. Find `register_settings` and rewrite it as:
+
+```python
+    def register_settings(self, app: FastAPI) -> None:
+        from users.services import UsersServices  # or whatever the dataclass is called
+        from users.settings import UsersSettings
+        from settings.registration import register_module_settings
+
+        register_module_settings(
+            app, "users", UsersSettings,
+            lambda s: UsersServices(settings=s),
+        )
+```
+
+If `UsersServices` doesn't exist as a standalone dataclass, look at the existing `register_settings` and use the same factory signature.
+
+- [ ] **Step 3: Rewrite env-based tests in `modules/users/tests/test_settings.py`**
+
+Every test that does `monkeypatch.setenv("SM_USERS_*", ...)` becomes: write to `SettingsStore`, call `hydrate_settings(UsersSettings, store, "users")`, assert on the result. Example:
+
+```python
+@pytest.mark.asyncio
+async def test_allow_signup_override_from_db(db_session):
+    from users.settings import UsersSettings
+    from settings.hydrate import hydrate_settings
+    from settings.service import SettingService
+    from settings.store import SettingsStore
+
+    store = SettingsStore(SettingService(db_session))
+    await store.set_override("users", "allow_signup", "true", "bool")
+
+    cfg = await hydrate_settings(UsersSettings, store, "users")
+    assert cfg.allow_signup is True
+```
+
+Apply the same pattern to every env-based test in that file.
+
+The production placeholder-secret tests still work — pass values into `UsersSettings(...)` directly, no env needed.
+
+- [ ] **Step 4: Run the users test suite**
+
+Run: `uv run pytest modules/users/tests/test_settings.py -v`
+Expected: PASS.
+
+- [ ] **Step 5: Run the full users suite**
+
+Run: `uv run pytest modules/users/tests/ -v`
+Expected: PASS.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add modules/users/users/settings.py modules/users/users/module.py modules/users/tests/test_settings.py
+git commit -m "refactor(users): move UsersSettings off env to DB-backed"
+```
+
+---
+
+### Task 3.3: Migrate background_tasks module
+
+**Files:**
+- Modify: `modules/background_tasks/background_tasks/settings.py`
+- Modify: `modules/background_tasks/background_tasks/module.py`
+- Modify: `modules/background_tasks/tests/` (any env-based tests)
+
+- [ ] **Step 1: Strip env config + annotate `requires_restart`**
+
+Replace the `SettingsConfigDict` line and update field definitions for Celery-critical fields:
+
+```python
+from pydantic import Field
+
+# ...
+
+class BackgroundTasksSettings(BaseSettings):
+    model_config = SettingsConfigDict(extra="ignore")
+
+    broker_url: str = Field(
+        default=DEFAULT_BROKER_URL,
+        json_schema_extra={"requires_restart": True, "group": "Celery"},
+    )
+    result_backend: str = Field(
+        default=DEFAULT_RESULT_BACKEND,
+        json_schema_extra={"requires_restart": True, "group": "Celery"},
+    )
+    task_default_queue: str = Field(
+        default=DEFAULT_QUEUE,
+        json_schema_extra={"requires_restart": True, "group": "Celery"},
+    )
+    # rest unchanged
+```
+
+Keep the localhost-in-production validator.
+
+- [ ] **Step 2: Update `register_settings` to use the helper**
+
+Same pattern as Task 3.2.
+
+- [ ] **Step 3: Update any env-based tests to write to the store**
+
+Same pattern as Task 3.2 — apply to every `monkeypatch.setenv("SM_BG_TASKS_*", ...)` in `modules/background_tasks/tests/`.
+
+- [ ] **Step 4: Run the background_tasks test suite**
+
+Run: `uv run pytest modules/background_tasks/tests/ -v`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add modules/background_tasks/
+git commit -m "refactor(background_tasks): move settings off env; mark Celery fields requires_restart"
+```
+
+---
+
+### Task 3.4: Migrate file_storage module
+
+**Files:**
+- Modify: `modules/file_storage/file_storage/settings.py`
+- Modify: `modules/file_storage/file_storage/module.py`
+- Modify: `modules/file_storage/tests/` (any env-based tests)
+
+Same pattern as 3.2. Group S3 fields: `json_schema_extra={"group": "S3"}`. Group filesystem fields: `"group": "Filesystem"`.
+
+- [ ] **Step 1: Strip env config; add group metadata**
+
+```python
+    model_config = SettingsConfigDict(extra="ignore")
+
+    backend: str = constants.DEFAULT_BACKEND
+    fs_root_path: str = Field(default=constants.DEFAULT_FS_ROOT, json_schema_extra={"group": "Filesystem"})
+    s3_bucket: str = Field(default="", json_schema_extra={"group": "S3"})
+    s3_region: str = Field(default="", json_schema_extra={"group": "S3"})
+    s3_access_key_id: str = Field(default="", json_schema_extra={"group": "S3"})
+    s3_secret_access_key: str = Field(default="", json_schema_extra={"group": "S3"})
+    s3_endpoint_url: str = Field(default="", json_schema_extra={"group": "S3"})
+    s3_presign_ttl_seconds: int = Field(default=constants.DEFAULT_PRESIGN_TTL_SECONDS, json_schema_extra={"group": "S3"})
+```
+
+- [ ] **Step 2: Update `register_settings` to use the helper**
+
+Same pattern as 3.2.
+
+- [ ] **Step 3: Update env-based tests**
+
+Same pattern as 3.2.
+
+- [ ] **Step 4: Run tests**
+
+Run: `uv run pytest modules/file_storage/tests/ -v`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add modules/file_storage/
+git commit -m "refactor(file_storage): move settings off env; group fields by backend"
+```
+
+---
+
+### Task 3.5: Migrate datasets module
+
+Same pattern — tiny surface.
+
+**Files:**
+- Modify: `modules/datasets/datasets/settings.py`
+- Modify: `modules/datasets/datasets/module.py`
+- Modify: `modules/datasets/tests/` if any env-based tests exist
+
+- [ ] **Step 1: Strip env config**
+
+```python
+    model_config = SettingsConfigDict(extra="ignore")
+```
+
+- [ ] **Step 2: Update `register_settings`**
+
+Same pattern.
+
+- [ ] **Step 3: Update env-based tests (if any)**
+
+- [ ] **Step 4: Run**
+
+Run: `uv run pytest modules/datasets/tests/ -v`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add modules/datasets/
+git commit -m "refactor(datasets): move settings off env (DB-backed)"
+```
+
+---
+
+### Task 3.6: Full suite check after migrations
+
+- [ ] **Step 1: Run entire test suite**
+
+Run: `make test`
+Expected: PASS.
+
+- [ ] **Step 2: Run lint**
+
+Run: `make lint`
+Expected: PASS.
+
+- [ ] **Step 3: Run doctor**
+
+Run: `make doctor`
+Expected: PASS (no new diagnostic errors).
+
+If anything breaks in consumer modules (code that used `SM_<MODULE>_*` at import time), fix those sites: read from `app.state.<package>.settings.<field>` instead.
+
+---
+
+## Phase 4: API endpoints for module settings
+
+### Task 4.1: Extend `_module_settings.py` with field-type and group metadata
+
+**Files:**
+- Modify: `modules/settings/settings/_module_settings.py`
+- Modify: `modules/settings/tests/test_module_settings.py` (or create)
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+# modules/settings/tests/test_module_settings.py
+from __future__ import annotations
+
+from fastapi import FastAPI
+from pydantic import Field
+from pydantic_settings import BaseSettings
+from simple_module_core.services import Services
+
+from settings.services import SettingsServices
+from settings.settings import SettingsSettings
+from settings._module_settings import collect_module_settings
+
+
+class _DemoCfg(BaseSettings):
+    allow: bool = False
+    port: int = Field(default=25, json_schema_extra={"requires_restart": True, "group": "SMTP"})
+    host: str = Field(default="localhost", json_schema_extra={"group": "SMTP"})
+    secret: str = ""  # name implies secret — must be masked
+
+
+def test_collect_exposes_type_requires_restart_group():
+    app = FastAPI()
+    app.state.settings = SettingsServices(settings=SettingsSettings())
+    app.state.settings.module_registry.register("demo", _DemoCfg)
+
+    class _DemoServices:
+        settings = _DemoCfg()
+
+    app.state.demo = _DemoServices()
+    app.state.sm = Services(
+        settings=None, db=None, event_bus=None, menu_registry=None,
+        permissions=None, feature_flags=None, health_registry=None,
+        i18n_registry=None, inertia_config=None, modules=(),
+    )
+
+    views = collect_module_settings(app)
+    demo = next(v for v in views if v.package == "demo")
+    by_name = {f.name: f for f in demo.fields}
+    assert by_name["allow"].type == "bool"
+    assert by_name["port"].type == "int"
+    assert by_name["port"].requires_restart is True
+    assert by_name["port"].group == "SMTP"
+    assert by_name["host"].group == "SMTP"
+    assert by_name["allow"].group is None
+    assert by_name["secret"].is_secret is True
+```
+
+- [ ] **Step 2: Run and confirm failure**
+
+Run: `uv run pytest modules/settings/tests/test_module_settings.py -v`
+Expected: FAIL — `type` / `requires_restart` / `group` attributes don't exist on `ModuleSettingField`.
+
+- [ ] **Step 3: Add the metadata to `ModuleSettingField` + extractor**
+
+In `modules/settings/settings/_module_settings.py`, extend the dataclass:
+
+```python
+@dataclass(frozen=True, slots=True)
+class ModuleSettingField:
+    name: str
+    env_var: str
+    value: Any
+    default: Any
+    description: str
+    is_secret: bool
+    type: str  # one of "bool" | "int" | "float" | "string" | "json"
+    requires_restart: bool
+    group: str | None
+```
+
+Extend `_field_view` to read the type (via `value_type_for_field` from `hydrate.py`) and the `json_schema_extra` on the FieldInfo:
+
+```python
+from settings.hydrate import value_type_for_field
+
+def _field_view(name: str, settings: BaseSettings, prefix: str) -> ModuleSettingField:
+    info = type(settings).model_fields[name]
+    raw_value = getattr(settings, name)
+    is_secret = bool(_SECRET_PATTERNS.search(name))
+    extra = info.json_schema_extra or {}
+    if not isinstance(extra, dict):
+        extra = {}
+    return ModuleSettingField(
+        name=name,
+        env_var=f"{prefix}{name.upper()}" if prefix else "",
+        value=_mask(raw_value) if is_secret else raw_value,
+        default=_mask(info.default) if is_secret else info.default,
+        description=info.description or "",
+        is_secret=is_secret,
+        type=value_type_for_field(type(settings), name),
+        requires_restart=bool(extra.get("requires_restart", False)),
+        group=extra.get("group"),
+    )
+```
+
+Update `serialize` to include the new keys.
+
+- [ ] **Step 4: Run and confirm pass**
+
+Run: `uv run pytest modules/settings/tests/test_module_settings.py -v`
+Expected: PASS.
+
+- [ ] **Step 5: Verify file is still under the 300-line cap**
+
+Run: `uv run python scripts/check_file_size.py modules/settings/settings/_module_settings.py`
+Expected: under 300 lines.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add modules/settings/settings/_module_settings.py modules/settings/tests/test_module_settings.py
+git commit -m "feat(settings): expose type, requires_restart, group on module setting fields"
+```
+
+---
+
+### Task 4.2: GET/PUT/DELETE endpoints for module settings
+
+**Files:**
+- Create: `modules/settings/settings/endpoints/module_api.py`
+- Modify: `modules/settings/settings/module.py` (include router)
+- Test: `modules/settings/tests/test_module_api.py`
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+# modules/settings/tests/test_module_api.py
+from __future__ import annotations
+
+import pytest
+
+
+@pytest.mark.asyncio
+async def test_get_modules_returns_registered_packages(authenticated_client):
+    resp = await authenticated_client.get("/api/settings/modules")
+    assert resp.status_code == 200
+    payload = resp.json()
+    packages = {m["package"] for m in payload["modules"]}
+    # The settings module registers itself; host is registered too.
+    assert {"settings", "host"} <= packages
+
+
+@pytest.mark.asyncio
+async def test_put_module_setting_persists_and_hot_reloads(authenticated_client, app):
+    resp = await authenticated_client.put(
+        "/api/settings/modules/host",
+        json={"multi_tenant": True},
+    )
+    assert resp.status_code == 200, resp.text
+    assert app.state.host.settings.multi_tenant is True
+
+
+@pytest.mark.asyncio
+async def test_put_validation_error_surfaces_422(authenticated_client, app):
+    # i18n_default_locale must be in i18n_supported_locales
+    resp = await authenticated_client.put(
+        "/api/settings/modules/host",
+        json={"i18n_default_locale": "de"},  # supported only has "en" by default
+    )
+    assert resp.status_code == 422
+    assert "i18n_default_locale" in resp.text
+
+
+@pytest.mark.asyncio
+async def test_delete_field_resets_to_default(authenticated_client, app):
+    await authenticated_client.put(
+        "/api/settings/modules/host", json={"multi_tenant": True}
+    )
+    assert app.state.host.settings.multi_tenant is True
+
+    resp = await authenticated_client.delete(
+        "/api/settings/modules/host/multi_tenant"
+    )
+    assert resp.status_code == 204
+    assert app.state.host.settings.multi_tenant is False  # back to default
+
+
+@pytest.mark.asyncio
+async def test_put_secret_mask_sentinel_is_noop(authenticated_client, app):
+    # First set a real value
+    await authenticated_client.put(
+        "/api/settings/modules/users",
+        json={"reset_password_token_secret": "real-secret-value-48-chars-long-xxxxxxxxxx"},
+    )
+    original = app.state.users.settings.reset_password_token_secret
+
+    # Submitting the mask sentinel should not change it
+    resp = await authenticated_client.put(
+        "/api/settings/modules/users",
+        json={"reset_password_token_secret": "••••••••"},
+    )
+    assert resp.status_code == 200
+    assert app.state.users.settings.reset_password_token_secret == original
+```
+
+- [ ] **Step 2: Run and confirm failure**
+
+Run: `uv run pytest modules/settings/tests/test_module_api.py -v`
+Expected: FAIL — endpoints don't exist.
+
+- [ ] **Step 3: Implement the endpoints**
+
+```python
+# modules/settings/settings/endpoints/module_api.py
+"""REST endpoints for the typed per-module settings UI."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+from pydantic import ValidationError
+
+from settings._module_settings import collect_module_settings, serialize
+from settings.constants import MODULE_PACKAGE
+from settings.deps import get_setting_service
+from settings.reload import apply_changes_and_reload
+from settings.service import SettingService
+from settings.store import SettingsStore
+
+_MASK_SENTINEL = "••••••••"
+
+router = APIRouter(prefix="/modules", tags=["Settings Modules"])
+
+
+@router.get("")
+async def list_modules(request: Request) -> dict[str, Any]:
+    """Return every registered module's current hydrated settings + metadata."""
+    views = collect_module_settings(request.app)
+    return {"modules": serialize(views)}
+
+
+@router.put("/{package}")
+async def update_module(
+    package: str,
+    request: Request,
+    service: SettingService = Depends(get_setting_service),
+) -> dict[str, Any]:
+    body = await request.json()
+    if not isinstance(body, dict):
+        raise HTTPException(400, "Body must be a JSON object")
+
+    # Strip secret mask sentinels — treated as "no change".
+    registry = getattr(request.app.state, MODULE_PACKAGE).module_registry
+    cls = registry.get(package)
+    if cls is None:
+        raise HTTPException(404, f"Unknown module: {package}")
+
+    from settings._module_settings import _SECRET_PATTERNS  # reuse secret regex
+    cleaned = {
+        k: v for k, v in body.items()
+        if not (_SECRET_PATTERNS.search(k) and v == _MASK_SENTINEL)
+    }
+    if not cleaned:
+        return {"ok": True, "changed": []}
+
+    bus = request.app.state.sm.event_bus
+    store = SettingsStore(service)
+    try:
+        updated = await apply_changes_and_reload(
+            request.app, bus, store, package=package, changes=cleaned
+        )
+    except ValidationError as exc:
+        raise HTTPException(422, detail=exc.errors()) from exc
+    except KeyError as exc:
+        raise HTTPException(400, detail=str(exc)) from exc
+
+    return {"ok": True, "changed": sorted(cleaned)}
+
+
+@router.delete("/{package}/{field}", status_code=204)
+async def reset_field(
+    package: str,
+    field: str,
+    request: Request,
+    service: SettingService = Depends(get_setting_service),
+) -> None:
+    registry = getattr(request.app.state, MODULE_PACKAGE).module_registry
+    cls = registry.get(package)
+    if cls is None:
+        raise HTTPException(404, f"Unknown module: {package}")
+    if field not in cls.model_fields:
+        raise HTTPException(404, f"Unknown field: {field}")
+
+    store = SettingsStore(service)
+    await store.clear_override(package, field)
+
+    # Re-hydrate from DB (now missing the override) and reassign.
+    from settings.hydrate import hydrate_settings
+    hydrated = await hydrate_settings(cls, store, package)
+    services = getattr(request.app.state, package)
+    services.settings = hydrated
+
+    from settings.contracts.events import SettingsReloaded
+    await request.app.state.sm.event_bus.publish(
+        SettingsReloaded(package=package, changed=(field,))
+    )
+```
+
+- [ ] **Step 4: Include the router in `settings/module.py`**
+
+In `SettingsModule.register_routes`:
+
+```python
+        from settings.endpoints.api import router as api
+        from settings.endpoints.module_api import router as module_api
+        from settings.endpoints.views import router as views
+
+        api_router.include_router(api)
+        api_router.include_router(module_api)
+        view_router.include_router(views)
+```
+
+- [ ] **Step 5: Run and confirm pass**
+
+Run: `uv run pytest modules/settings/tests/test_module_api.py -v`
+Expected: PASS (5 passed).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add modules/settings/settings/endpoints/module_api.py modules/settings/settings/module.py modules/settings/tests/test_module_api.py
+git commit -m "feat(settings): add GET/PUT/DELETE endpoints for per-module settings"
+```
+
+---
+
+## Phase 5: Admin UI — sidebar + main panel
+
+### Task 5.1: View endpoint returns serialized modules
+
+**Files:**
+- Modify: `modules/settings/settings/endpoints/views.py`
+
+The existing `modules_view` already calls `collect_module_settings`. It now serves the new editable page component. Rename the component to `Settings/ModulesEdit` to keep the old read-only `Settings/Modules` around during transition (we delete it at the end of Phase 5).
+
+- [ ] **Step 1: Add a new PAGE constant**
+
+In `modules/settings/settings/constants.py`:
+
+```python
+PAGE_MODULES_EDIT: Final = f"{MODULE_NAME}/ModulesEdit"
+```
+
+- [ ] **Step 2: Update `modules_view`**
+
+```python
+@router.get(VIEW_MODULES_PATH, response_model=None)
+async def modules_view(request: Request, inertia: InertiaDep) -> InertiaResponse:
+    views = collect_module_settings(request.app)
+    return await inertia.render(
+        "Settings/ModulesEdit",
+        {PROP_MODULES: serialize(views)},
+    )
+```
+
+- [ ] **Step 3: Commit the string change now (the page file comes next)**
+
+```bash
+git add modules/settings/settings/constants.py modules/settings/settings/endpoints/views.py
+git commit -m "chore(settings): point /settings/modules view at ModulesEdit page (pending)"
+```
+
+Note: build will fail until Task 5.2 lands — keep both commits close together.
+
+---
+
+### Task 5.2: `FieldInput` component — type-driven input
+
+**Files:**
+- Create: `modules/settings/settings/pages/components/FieldInput.tsx`
+- Test: `modules/settings/pages/components/FieldInput.test.tsx` (if JS tests exist in module — otherwise cover in the integration test)
+
+- [ ] **Step 1: Implement the component**
+
+```tsx
+// modules/settings/settings/pages/components/FieldInput.tsx
+import { useState } from 'react';
+
+export type FieldType = 'bool' | 'int' | 'float' | 'string' | 'json';
+
+export type FieldMeta = {
+  name: string;
+  type: FieldType;
+  value: unknown;
+  default: unknown;
+  description: string;
+  is_secret: boolean;
+  requires_restart: boolean;
+  group: string | null;
+  env_var: string;
+};
+
+type Props = {
+  field: FieldMeta;
+  onChange: (name: string, value: unknown) => void;
+  value: unknown;
+};
+
+export function FieldInput({ field, onChange, value }: Props) {
+  const [revealed, setRevealed] = useState(false);
+
+  if (field.is_secret && !revealed) {
+    return (
+      <div className="flex items-center gap-2">
+        <input
+          type="password"
+          value="••••••••"
+          readOnly
+          className="w-full rounded border px-2 py-1 font-mono text-sm"
+        />
+        <button
+          type="button"
+          className="text-sm text-primary hover:underline"
+          onClick={() => {
+            setRevealed(true);
+            onChange(field.name, ''); // start blank
+          }}
+        >
+          Set new value
+        </button>
+      </div>
+    );
+  }
+
+  switch (field.type) {
+    case 'bool':
+      return (
+        <input
+          type="checkbox"
+          checked={!!value}
+          onChange={(e) => onChange(field.name, e.target.checked)}
+        />
+      );
+    case 'int':
+      return (
+        <input
+          type="number"
+          step="1"
+          value={String(value ?? '')}
+          onChange={(e) => onChange(field.name, e.target.value === '' ? null : Number(e.target.value))}
+          className="w-full rounded border px-2 py-1 font-mono text-sm"
+        />
+      );
+    case 'float':
+      return (
+        <input
+          type="number"
+          step="any"
+          value={String(value ?? '')}
+          onChange={(e) => onChange(field.name, e.target.value === '' ? null : Number(e.target.value))}
+          className="w-full rounded border px-2 py-1 font-mono text-sm"
+        />
+      );
+    case 'json':
+      return (
+        <textarea
+          rows={3}
+          value={typeof value === 'string' ? value : JSON.stringify(value, null, 2)}
+          onChange={(e) => onChange(field.name, e.target.value)}
+          className="w-full rounded border px-2 py-1 font-mono text-xs"
+        />
+      );
+    default:
+      return (
+        <input
+          type="text"
+          value={String(value ?? '')}
+          onChange={(e) => onChange(field.name, e.target.value)}
+          className="w-full rounded border px-2 py-1 font-mono text-sm"
+        />
+      );
+  }
+}
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add modules/settings/settings/pages/components/FieldInput.tsx
+git commit -m "feat(settings-ui): add FieldInput component with type-driven rendering"
+```
+
+---
+
+### Task 5.3: `ModuleForm` component
+
+**Files:**
+- Create: `modules/settings/settings/pages/components/ModuleForm.tsx`
+
+- [ ] **Step 1: Implement**
+
+```tsx
+// modules/settings/settings/pages/components/ModuleForm.tsx
+import { router } from '@inertiajs/react';
+import { useMemo, useState } from 'react';
+import { FieldInput, type FieldMeta } from './FieldInput';
+
+export type ModuleView = {
+  module_name: string;
+  package: string;
+  env_prefix: string;
+  class_name: string;
+  fields: FieldMeta[];
+};
+
+type Props = { module: ModuleView };
+
+export function ModuleForm({ module: m }: Props) {
+  const initial = useMemo(() => {
+    const o: Record<string, unknown> = {};
+    for (const f of m.fields) o[f.name] = f.value;
+    return o;
+  }, [m]);
+
+  const [values, setValues] = useState<Record<string, unknown>>(initial);
+  const [errors, setErrors] = useState<Record<string, string>>({});
+  const [busy, setBusy] = useState(false);
+
+  const dirty = JSON.stringify(values) !== JSON.stringify(initial);
+
+  const grouped = useMemo(() => {
+    const g: Record<string, FieldMeta[]> = {};
+    for (const f of m.fields) {
+      const key = f.group ?? 'General';
+      (g[key] ??= []).push(f);
+    }
+    return g;
+  }, [m]);
+
+  async function onSave() {
+    setBusy(true);
+    setErrors({});
+    const changed: Record<string, unknown> = {};
+    for (const k of Object.keys(values)) {
+      if (JSON.stringify(values[k]) !== JSON.stringify(initial[k])) {
+        changed[k] = values[k];
+      }
+    }
+    const resp = await fetch(`/api/settings/modules/${m.package}`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(changed),
+    });
+    if (resp.status === 422) {
+      const body = await resp.json();
+      const fieldErrs: Record<string, string> = {};
+      for (const d of body.detail ?? []) {
+        if (d.loc && d.loc.length) fieldErrs[d.loc[d.loc.length - 1]] = d.msg;
+      }
+      setErrors(fieldErrs);
+    } else if (resp.ok) {
+      router.reload({ only: ['modules'] });
+    }
+    setBusy(false);
+  }
+
+  async function onReset(name: string) {
+    await fetch(`/api/settings/modules/${m.package}/${name}`, { method: 'DELETE' });
+    router.reload({ only: ['modules'] });
+  }
+
+  return (
+    <div className="space-y-6">
+      <header className="flex items-center justify-between border-b pb-3">
+        <div>
+          <h2 className="text-xl font-semibold">{m.module_name}</h2>
+          <p className="text-xs font-mono text-muted-foreground">{m.package}</p>
+        </div>
+        <button
+          type="button"
+          disabled={!dirty || busy}
+          onClick={onSave}
+          className="rounded bg-primary px-4 py-2 text-sm text-primary-foreground disabled:opacity-50"
+        >
+          {busy ? 'Saving…' : 'Save'}
+        </button>
+      </header>
+
+      {Object.entries(grouped).map(([group, fields]) => (
+        <section key={group} className="space-y-3">
+          <h3 className="text-sm font-semibold text-muted-foreground">{group}</h3>
+          {fields.map((f) => {
+            const isModified = JSON.stringify(values[f.name]) !== JSON.stringify(f.default);
+            return (
+              <div key={f.name} className="grid grid-cols-[1fr_2fr] gap-4 items-start">
+                <div>
+                  <label className="font-mono text-xs">{f.name}</label>
+                  {f.description && (
+                    <p className="mt-1 text-xs text-muted-foreground">{f.description}</p>
+                  )}
+                  {f.requires_restart && isModified && (
+                    <span className="mt-1 inline-block rounded bg-amber-100 px-1.5 py-0.5 text-[10px] uppercase text-amber-900">
+                      Requires restart
+                    </span>
+                  )}
+                </div>
+                <div>
+                  <FieldInput
+                    field={f}
+                    value={values[f.name]}
+                    onChange={(name, v) => setValues((prev) => ({ ...prev, [name]: v }))}
+                  />
+                  {isModified && (
+                    <button
+                      type="button"
+                      onClick={() => onReset(f.name)}
+                      className="mt-1 text-xs text-primary hover:underline"
+                    >
+                      Reset to default
+                    </button>
+                  )}
+                  {errors[f.name] && (
+                    <p className="mt-1 text-xs text-red-600">{errors[f.name]}</p>
+                  )}
+                </div>
+              </div>
+            );
+          })}
+        </section>
+      ))}
+    </div>
+  );
+}
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add modules/settings/settings/pages/components/ModuleForm.tsx
+git commit -m "feat(settings-ui): add ModuleForm with typed inputs, grouping, reset, validation"
+```
+
+---
+
+### Task 5.4: `ModulesEdit` page — sidebar layout
+
+**Files:**
+- Create: `modules/settings/settings/pages/ModulesEdit.tsx`
+
+- [ ] **Step 1: Implement**
+
+```tsx
+// modules/settings/settings/pages/ModulesEdit.tsx
+import { keys, useT } from '@simple-module/i18n';
+import { AuthenticatedLayout } from '@simple-module/ui/layouts/AuthenticatedLayout';
+import { useMemo, useState } from 'react';
+import type React from 'react';
+import { ModuleForm, type ModuleView } from './components/ModuleForm';
+import { ROUTES } from './routes';
+
+type Props = { modules: ModuleView[] };
+
+function ModulesEdit({ modules }: Props) {
+  const { t } = useT();
+  const [selected, setSelected] = useState(modules[0]?.package);
+  const [q, setQ] = useState('');
+
+  const filtered = useMemo(() => {
+    if (!q) return modules;
+    const query = q.toLowerCase();
+    return modules.filter(
+      (m) =>
+        m.module_name.toLowerCase().includes(query) ||
+        m.package.toLowerCase().includes(query) ||
+        m.fields.some((f) => f.name.toLowerCase().includes(query))
+    );
+  }, [modules, q]);
+
+  const current = modules.find((m) => m.package === selected);
+
+  return (
+    <div className="flex h-[calc(100vh-64px)]">
+      <aside className="w-64 border-r bg-muted/40 p-3 overflow-y-auto">
+        <input
+          type="text"
+          placeholder={t(keys.settings.modules.search_placeholder)}
+          value={q}
+          onChange={(e) => setQ(e.target.value)}
+          className="mb-3 w-full rounded border px-2 py-1 text-sm"
+        />
+        <nav className="space-y-1">
+          {filtered.map((m) => (
+            <button
+              key={m.package}
+              type="button"
+              onClick={() => setSelected(m.package)}
+              className={`block w-full rounded px-3 py-2 text-left text-sm ${
+                m.package === selected
+                  ? 'bg-primary text-primary-foreground'
+                  : 'hover:bg-muted'
+              }`}
+            >
+              <div className="font-medium">{m.module_name}</div>
+              <div className="text-xs opacity-70">
+                {m.fields.length} {t(keys.settings.modules.field_count_suffix)}
+              </div>
+            </button>
+          ))}
+        </nav>
+        <div className="mt-4 border-t pt-3 text-xs">
+          <a href={ROUTES.browse} className="text-primary hover:underline">
+            {t(keys.settings.modules.browse_free_form_link)}
+          </a>
+        </div>
+      </aside>
+
+      <main className="flex-1 overflow-y-auto p-6">
+        {current ? (
+          <ModuleForm module={current} />
+        ) : (
+          <p className="text-muted-foreground">
+            {t(keys.settings.modules.empty_title)}
+          </p>
+        )}
+      </main>
+    </div>
+  );
+}
+
+ModulesEdit.layout = (page: React.ReactNode) => (
+  <AuthenticatedLayout>{page}</AuthenticatedLayout>
+);
+export default ModulesEdit;
+```
+
+- [ ] **Step 2: Add the required i18n keys**
+
+In `modules/settings/settings/locales/en.json`, under the existing `"modules"` object, add:
+
+```json
+"search_placeholder": "Search modules or fields…",
+"field_count_suffix": "fields",
+"browse_free_form_link": "View free-form settings"
+```
+
+And the equivalent keys in other locale files (copy from `en.json` and translate or leave the English as a placeholder).
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add modules/settings/settings/pages/ModulesEdit.tsx modules/settings/settings/locales/
+git commit -m "feat(settings-ui): add ModulesEdit page (sidebar + main panel layout)"
+```
+
+---
+
+### Task 5.5: Delete the old read-only `Modules.tsx`
+
+- [ ] **Step 1: Remove the old page**
+
+```bash
+git rm modules/settings/settings/pages/Modules.tsx
+```
+
+- [ ] **Step 2: Remove the old PAGE constant and any references**
+
+In `modules/settings/settings/constants.py`, drop `PAGE_MODULES` if nothing else references it (grep first).
+
+- [ ] **Step 3: Run `make gen-pages` and restart dev**
+
+Run: `make gen-pages`
+
+- [ ] **Step 4: Run make lint + doctor**
+
+Run: `make lint && make doctor`
+Expected: PASS.
+
+- [ ] **Step 5: Manual smoke test**
+
+Start `make dev`, visit `http://localhost:8000/settings/modules`, verify sidebar renders with modules, clicking one shows fields, toggling `host.multi_tenant` saves.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add modules/settings/settings/constants.py
+git commit -m "chore(settings): remove read-only Modules page (replaced by ModulesEdit)"
+```
+
+---
+
+### Task 5.6: E2E test
+
+**Files:**
+- Create: `tests/e2e/test_settings_ui.py`
+
+- [ ] **Step 1: Write the E2E test**
+
+```python
+# tests/e2e/test_settings_ui.py
+import pytest
+from playwright.async_api import async_playwright
+
+
+@pytest.mark.e2e
+@pytest.mark.asyncio
+async def test_toggle_setting_takes_effect_without_restart(live_server, admin_cookie):
+    async with async_playwright() as p:
+        browser = await p.chromium.launch()
+        context = await browser.new_context()
+        await context.add_cookies([admin_cookie])
+        page = await context.new_page()
+
+        await page.goto(f"{live_server}/settings/modules")
+        await page.click("text=Users")
+        await page.check('input[type=checkbox]:near(:text("allow_signup"))')
+        await page.click('button:has-text("Save")')
+        await page.wait_for_load_state("networkidle")
+
+        # allow_signup=true means /users/register is reachable
+        await page.goto(f"{live_server}/users/register")
+        assert "Register" in await page.title() or 200 == page.response.status
+```
+
+- [ ] **Step 2: Run (requires `make dev` + playwright chromium installed)**
+
+Run: `make test-e2e`
+Expected: PASS.
+
+If the test fails because of selector brittleness, refine selectors — the point is to verify hot-reload end-to-end.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add tests/e2e/test_settings_ui.py
+git commit -m "test(e2e): verify settings-UI hot-reload for users.allow_signup"
+```
+
+---
+
+## Phase 6: Import-from-env CLI
+
+### Task 6.1: `sm-settings import-from-env` command
+
+**Files:**
+- Modify: `modules/settings/settings/cli.py` (create if missing; check `pyproject.toml` for existing entry point)
+- Modify: `modules/settings/pyproject.toml` (add `[project.scripts]` entry)
+- Test: `modules/settings/tests/test_cli_import.py`
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+# modules/settings/tests/test_cli_import.py
+from __future__ import annotations
+
+import pytest
+
+from settings.cli import import_from_env_impl
+
+
+@pytest.mark.asyncio
+async def test_import_from_env_writes_overrides(db_session, monkeypatch, app):
+    monkeypatch.setenv("SM_USERS_ALLOW_SIGNUP", "true")
+    monkeypatch.setenv("SM_USERS_SMTP_PORT", "2525")
+    monkeypatch.setenv("SM_BG_TASKS_RETENTION_DAYS", "30")
+
+    from settings.service import SettingService
+    from settings.store import SettingsStore
+
+    store = SettingsStore(SettingService(db_session))
+    n = await import_from_env_impl(app, store)
+
+    users = await store.get_overrides("users")
+    bg = await store.get_overrides("background_tasks")
+    assert users["allow_signup"] == ("true", "bool")
+    assert users["smtp_port"] == ("2525", "int")
+    assert bg["retention_days"] == ("30", "int")
+    assert n == 3
+
+
+@pytest.mark.asyncio
+async def test_import_ignores_unknown_env(db_session, monkeypatch, app):
+    monkeypatch.setenv("SM_USERS_DOES_NOT_EXIST", "value")
+
+    from settings.service import SettingService
+    from settings.store import SettingsStore
+
+    store = SettingsStore(SettingService(db_session))
+    n = await import_from_env_impl(app, store)
+    assert n == 0
+    assert await store.get_overrides("users") == {}
+```
+
+- [ ] **Step 2: Run and confirm failure**
+
+Run: `uv run pytest modules/settings/tests/test_cli_import.py -v`
+Expected: FAIL — ImportError.
+
+- [ ] **Step 3: Implement the CLI impl**
+
+```python
+# modules/settings/settings/cli.py
+"""CLI entry points for the Settings module.
+
+``sm-settings import-from-env`` — reads every ``SM_<MODULE>_*`` from the
+current process environment and writes each matching field as an override
+to the ``Setting`` table. Idempotent.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import sys
+
+from fastapi import FastAPI
+
+from settings.constants import MODULE_PACKAGE
+from settings.hydrate import value_type_for_field
+from settings.store import SettingsStore
+
+
+def _env_prefix_for(package: str) -> str:
+    if package == "background_tasks":
+        return "SM_BG_TASKS_"
+    if package == "file_storage":
+        return "SM_FILE_STORAGE_"
+    if package == "host":
+        return "SM_"  # careful — host catches many vars
+    return f"SM_{package.upper()}_"
+
+
+async def import_from_env_impl(app: FastAPI, store: SettingsStore) -> int:
+    """Read env vars matching each registered module's prefix; write overrides.
+
+    Returns the number of overrides written.
+    """
+    registry = getattr(app.state, MODULE_PACKAGE).module_registry
+    count = 0
+    for package, cls in registry.items():
+        prefix = _env_prefix_for(package)
+        for field_name in cls.model_fields:
+            env_name = f"{prefix}{field_name.upper()}"
+            if env_name not in os.environ:
+                continue
+            raw = os.environ[env_name]
+            vtype = value_type_for_field(cls, field_name)
+            await store.set_override(package, field_name, raw, vtype)
+            count += 1
+    return count
+
+
+def main() -> int:
+    """Entry point — builds a temporary app to read the registry, then imports."""
+    from simple_module_hosting.app_builder import create_app
+    from settings.service import SettingService
+
+    app = create_app()
+
+    async def run():
+        async with app.state.sm.db.session_factory() as session:
+            store = SettingsStore(SettingService(session))
+            n = await import_from_env_impl(app, store)
+            await session.commit()
+            print(f"Imported {n} override(s) from environment.")
+            return 0
+
+    return asyncio.run(run())
+
+
+if __name__ == "__main__":
+    sys.exit(main())
+```
+
+- [ ] **Step 4: Register the CLI in `modules/settings/pyproject.toml`**
+
+Add under `[project.scripts]`:
+
+```toml
+[project.scripts]
+sm-settings = "settings.cli:main"
+```
+
+(If `[project.scripts]` already exists, append the entry.)
+
+- [ ] **Step 5: Reinstall workspace so the CLI is discoverable**
+
+Run: `uv sync --all-packages`
+
+- [ ] **Step 6: Run the CLI test**
+
+Run: `uv run pytest modules/settings/tests/test_cli_import.py -v`
+Expected: 2 passed.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add modules/settings/settings/cli.py modules/settings/pyproject.toml modules/settings/tests/test_cli_import.py
+git commit -m "feat(settings): add sm-settings import-from-env CLI"
+```
+
+---
+
+## Phase 7: Cleanup — `.env.example`, compose, README
+
+### Task 7.1: Shrink `.env.example`
+
+**Files:**
+- Modify: `.env.example`
+
+- [ ] **Step 1: Replace with the bootstrap-only example**
+
+```bash
+# .env.example
+# Only SM_DATABASE_URL is required. Everything else has sensible defaults.
+# All module-level settings (SMTP, Celery, users, etc.) are now managed in
+# the admin UI at /settings/modules — no env vars needed.
+
+# Database (required)
+SM_DATABASE_URL=sqlite+aiosqlite:///./app.db
+# SM_DATABASE_URL=postgresql+asyncpg://sm:sm@localhost:5432/simple_module
+
+# Process identity (production must override SM_SECRET_KEY)
+SM_ENVIRONMENT=development
+SM_SECRET_KEY=change-me-in-production
+
+# Dev-only: Vite asset URL (ignored in production builds)
+SM_VITE_DEV_URL=http://localhost:5050
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add .env.example
+git commit -m "chore: shrink .env.example to bootstrap-only (DB, environment, secret, vite)"
+```
+
+---
+
+### Task 7.2: Update `docker-compose.yml`
+
+**Files:**
+- Modify: `docker-compose.yml`
+
+- [ ] **Step 1: Remove `SM_BG_TASKS_*` env entries**
+
+The compose file currently sets `SM_BG_TASKS_BROKER_URL=redis://redis:6379/0` etc. Update `BackgroundTasksSettings` defaults in Task 3.3 so `broker_url` defaults to `redis://redis:6379/0` — this way dev-compose works from defaults. Then delete the compose env lines.
+
+Inspect `docker-compose.yml:36-40` and `docker-compose.yml:61-65` and remove the `SM_BG_TASKS_*` env entries. Keep `SM_DATABASE_URL`.
+
+Actually: the compose defaults must match the service hostnames (`redis`), which differ from local dev (`localhost`). Two options:
+- **Option A** — keep env override in compose. Reasonable compromise; compose is "deployment", not module config.
+- **Option B** — change Celery defaults to `redis://redis:6379/*` and tell local-dev users to override via `sm-settings` CLI after first boot.
+
+Pick **A** — compose env stays. The spec's promise ("only DB URL in env") refers to the user's local `.env.example`, not CI/compose overrides which are container-specific plumbing.
+
+So: **no changes to `docker-compose.yml`** for this task. Document the exception:
+
+- [ ] **Step 2: Document the compose exception in README**
+
+Done in Task 7.3.
+
+- [ ] **Step 3: No commit needed for this task**
+
+---
+
+### Task 7.3: Rewrite README env-var section
+
+**Files:**
+- Modify: `README.md`
+
+- [ ] **Step 1: Replace the env-var table**
+
+Replace the existing env-var table (around `README.md:95-106`) with:
+
+```markdown
+## Configuration
+
+Local deployments only need one env var — everything else has sensible defaults and is managed in the admin UI at `/settings/modules`.
+
+| Variable | Default | Required |
+|---|---|---|
+| `SM_DATABASE_URL` | `sqlite+aiosqlite:///./app.db` | Yes — async URL. Postgres: `postgresql+asyncpg://...` |
+| `SM_ENVIRONMENT` | `development` | No — any value other than `development`, `test`, `testing` triggers strict discovery and placeholder-secret checks |
+| `SM_SECRET_KEY` | `change-me-in-production` | No in dev; **must** be overridden in production |
+| `SM_VITE_DEV_URL` | `http://localhost:5050` | Dev only |
+
+Power users can still override the following bootstrap knobs via env if needed: `SM_DB_POOL_SIZE`, `SM_DB_MAX_OVERFLOW`, `SM_DB_POOL_PRE_PING`, `SM_DB_POOL_RECYCLE`, `SM_DEBUG`, `SM_LOG_LEVEL`, `SM_LOG_FORMAT`, `SM_MODULES_ENABLED`. These are needed before the DB connection is open.
+
+All module-level settings — users, SMTP, Celery broker, file storage backend, etc. — live in the admin UI. After upgrading an existing deployment, run once:
+
+```bash
+uv run sm-settings import-from-env
+```
+
+to seed DB overrides from the current `SM_*` environment.
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add README.md
+git commit -m "docs: rewrite README config section — bootstrap vars only + UI pointer"
+```
+
+---
+
+## Phase 8: Final verification
+
+### Task 8.1: Full lint + tests + doctor
+
+- [ ] **Step 1: Run the full pipeline**
+
+Run: `make lint && make test && make doctor`
+Expected: all PASS.
+
+- [ ] **Step 2: Check 300-line cap on touched files**
+
+Run: `uv run python scripts/check_file_size.py`
+Expected: PASS.
+
+- [ ] **Step 3: Manual smoke test**
+
+Start `make dev`. Visit `/settings/modules`. Verify:
+- Sidebar shows `Users`, `Background Tasks`, `Datasets`, `File Storage`, `Settings`, `Host`.
+- Clicking `Users` shows fields grouped by `SMTP`, `General`, etc.
+- Toggling `allow_signup` → Save → no reload needed → `/users/register` reachable.
+- Editing `broker_url` shows "Requires restart" badge once the value differs from live.
+- Editing a secret field replaces the mask with a blank input.
+- "Reset to default" appears when a field differs from its pydantic default; clicking it removes the DB row.
+
+### Task 8.2: Write release note snippet
+
+**Files:**
+- Create: `docs/release-notes/2026-04-21-db-backed-settings.md`
+
+- [ ] **Step 1: Write the note**
+
+```markdown
+# DB-backed module settings
+
+Every `SM_<MODULE>_*` env var has moved to the admin UI at `/settings/modules`.
+`.env` now only needs `SM_DATABASE_URL` in typical deployments.
+
+## Upgrading
+
+After deploying this release:
+
+1. Run `uv run sm-settings import-from-env` once to seed the DB with your current environment values.
+2. Remove the `SM_<MODULE>_*` entries from your `.env` / deployment config (they're no longer read).
+
+## Breaking changes
+
+Setting `SM_USERS_ALLOW_SIGNUP=true` (or any other `SM_<MODULE>_*`) in the environment no longer has any effect. Use the admin UI or the `sm-settings` CLI.
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add docs/release-notes/2026-04-21-db-backed-settings.md
+git commit -m "docs: add release note for DB-backed module settings"
+```
+
+---
+
+## Final commit and PR
+
+- [ ] **Step 1: Double-check everything is committed**
+
+Run: `git status`
+Expected: `nothing to commit, working tree clean`.
+
+- [ ] **Step 2: Run the full test suite one more time**
+
+Run: `make test && make lint && make doctor`
+Expected: PASS.
+
+- [ ] **Step 3: Push and open PR (only if the user has asked for a PR)**
+
+Do not push or open a PR unless the user explicitly requests it.
+
+---
+
+## Appendix — open decisions carried from the spec
+
+These were marked "open decisions to resolve during plan writing" in the spec. Resolutions baked into the tasks above:
+
+1. **Metadata shape**: chose plain `Field(..., json_schema_extra={"requires_restart": True, "group": "SMTP"})` — no new helper function. Keeps module code readable and avoids yet another API to learn.
+
+2. **Event bus sync/async**: `EventBus.publish` is async (uses `asyncio.gather`). `apply_changes_and_reload` `await`s the publish so handlers run before the API responds.
+
+3. **`list_packages` source**: uses the in-memory registry (`ModuleSettingsRegistry.all_packages()`) as the source of truth during the app's lifetime. A separate `sm-settings prune-orphans` command (future follow-up, not in this plan) would scan the DB for `Setting` rows whose package is no longer registered.
diff --git a/docs/superpowers/specs/2026-04-21-db-backed-module-settings-design.md b/docs/superpowers/specs/2026-04-21-db-backed-module-settings-design.md
new file mode 100644
index 00000000..bb5320bc
--- /dev/null
+++ b/docs/superpowers/specs/2026-04-21-db-backed-module-settings-design.md
@@ -0,0 +1,225 @@
+# DB-backed Module Settings with Admin UI
+
+**Date:** 2026-04-21
+**Status:** Design — approved for implementation planning
+
+## Goal
+
+Collapse the `.env` surface to a four-variable bootstrap and move every other configuration value into the database, editable through a typed per-module admin UI. Defaults stay in code (pydantic `BaseSettings` subclasses); DB rows override defaults; the UI is the primary interface for operators.
+
+## Scope
+
+**In scope.**
+- Replace `SM_<MODULE>_*` env reading with DB-backed resolution for every module's `BaseSettings`.
+- New admin UI at `/settings/modules` (replaces today's read-only view) — sidebar + main panel, typed inputs, per-module save, per-field reset-to-default.
+- Hot-reload on save: rebuild `app.state.<package>.settings` and fire a `settings.reloaded` event.
+- Secret fields masked in UI (write-only).
+- One-shot `sm-settings import-from-env` CLI to migrate existing deployments.
+
+**Out of scope.**
+- Tenant-scoped and user-scoped overrides in the new UI. The existing free-form `/settings` Browse/Create/Edit pages — which already support all three scopes — stay for power users.
+- Encryption-at-rest for secrets. Secrets live plaintext in the `Setting` table; the UI masks on display.
+- Config-file layer (YAML/TOML). DB is the only override source.
+
+## Non-goals & invariants
+
+- **BaseSettings stays the schema source of truth.** All defaults, types, `Field(description=...)`, and `model_validator` logic remain in each module's settings class. The DB stores only overrides.
+- **No env-var fallback.** After this change, setting `SM_USERS_ALLOW_SIGNUP=true` in the environment has no effect. This is an intentional clean cut — see Migration below.
+- **The free-form `Setting` CRUD and its scoped resolution are preserved.** This feature adds a namespaced view on top; it does not rewrite the scoped resolver.
+
+## Env-var surface after change
+
+```
+SM_DATABASE_URL=sqlite+aiosqlite:///./app.db
+SM_ENVIRONMENT=development
+SM_SECRET_KEY=change-me-in-production
+SM_VITE_DEV_URL=http://localhost:5050
+```
+
+These four are the **bootstrap group**: needed before the DB is available (`SM_DATABASE_URL`), before strict-discovery runs (`SM_ENVIRONMENT`), before `SessionMiddleware` is mounted (`SM_SECRET_KEY`), or before Vite asset URLs are computed in dev (`SM_VITE_DEV_URL`). They stay env-only and load via a new `BootstrapSettings` class in `framework/hosting`.
+
+Everything else — `SM_USERS_*`, `SM_BG_TASKS_*`, `SM_DATASETS_*`, `SM_FILE_STORAGE_*`, `SM_SETTINGS_*`, plus non-bootstrap host fields (`multi_tenant`, `tenant_header`, `i18n_default_locale`, etc.) — moves to DB.
+
+## Architecture
+
+Four pieces:
+
+### 1. `SettingsStore` (new, in `settings` module)
+
+Thin wrapper over the existing `SettingService` that speaks in terms of `(package, field_name)` pairs, hard-coded to `scope=SYSTEM`, `scope_id="system"`. Provides:
+
+```python
+class SettingsStore:
+    def __init__(self, service: SettingService) -> None: ...
+
+    async def get_overrides(self, package: str) -> dict[str, str]:
+        """All stored overrides for a module, as raw string values."""
+
+    async def set_override(self, package: str, field: str, value: str, value_type: str) -> None: ...
+
+    async def clear_override(self, package: str, field: str) -> None: ...
+
+    async def list_packages(self) -> list[str]: ...
+```
+
+Keys in the `Setting` table are written as `"<package>.<field>"` to avoid collision with user-defined free-form keys. `scope="system"`, `scope_id="system"`.
+
+### 2. `load_settings` / `hydrate_settings`
+
+```python
+def load_settings(cls: type[T]) -> T:
+    """Construct a BaseSettings using pydantic defaults only (no DB, no env)."""
+
+async def hydrate_settings(cls: type[T], store: SettingsStore, package: str) -> T:
+    """Return a BaseSettings where each field is (DB value > default)."""
+```
+
+`hydrate_settings` reads raw string overrides, parses each according to `value_type`, and builds the settings with `cls(**parsed_overrides)`. Pydantic runs field validators and `model_validator` — any failure raises with per-field error info.
+
+### 3. Hot-reload mechanism
+
+The settings module owns a registry: `{package: BaseSettings_subclass}`, populated during `register_settings` of each module via a small helper:
+
+```python
+def register_module_settings(app: FastAPI, package: str, cls: type[BaseSettings]) -> None:
+    """Install defaults on app.state.<package>.settings and register the class
+    for later hydration / reload."""
+```
+
+On save (API endpoint):
+1. Look up the registered `cls` for the package.
+2. Merge requested changes with existing DB overrides.
+3. Construct `cls(**merged)` — fails loudly with pydantic validation errors.
+4. Write changed rows to `Setting` via `SettingsStore`.
+5. Reassign `app.state.<package>.settings = new_instance`.
+6. Fire `settings.reloaded` event with `{package, changed: [field_names]}`.
+
+### 4. UI (`/settings/modules`)
+
+Sidebar + main panel. See Section 4 of the brainstorm for the full layout; key pieces:
+
+- Sidebar lists registered modules, with search that also fuzzy-matches field names.
+- Main panel renders the selected module's fields as a typed form, grouped by optional `group` metadata. Save button is disabled until dirty.
+- Per-field "Reset to default" link; "Requires restart" badge when applicable.
+- Secret fields masked with "Set new value" toggle.
+- Validation errors from the save attempt surface inline.
+- Link back to the existing `/settings` free-form Browse for power users.
+
+Permissions: reuse the existing `settings.manage` permission from `modules/settings/settings/constants.py`.
+
+## Data model & value encoding
+
+Reuse the existing `Setting` table — no migration needed:
+
+- `key = "<package>.<field>"`
+- `scope = "system"`, `scope_id = "system"`
+- `value` — string; for complex types, JSON-encoded
+- `value_type` — one of `"string" | "bool" | "int" | "float" | "json"`; drives the hydrator's parsing
+- `description` — mirror of `Field(description=...)` for reference; not source of truth
+
+Secret classification reuses the existing `_SECRET_PATTERNS` regex in `_module_settings.py` (`password|secret|api_key|private_key|token_secret`). Secrets are plaintext in `Setting.value` but masked (`••••••••`) in API responses; on update, the mask sentinel is treated as "no change".
+
+### Field-level metadata
+
+`_module_settings.py` is extended so each discovered field exposes:
+- `type` — one of `bool | int | float | string | select | json`
+- `enum_values` — populated when the pydantic field uses `Literal[...]` or `Field(pattern="^(a|b)$")` with a parseable pattern
+- `is_secret` — via the existing regex
+- `requires_restart` — read from `json_schema_extra={"requires_restart": True}` on the pydantic `Field(...)`
+- `group` — optional subsection label (`"SMTP"`, `"Rate limiting"`), read from the same `json_schema_extra`
+
+Modules opt into `requires_restart` / `group` by annotating fields — see the "requires_restart fields" table below.
+
+## Boot order
+
+Today's sequence (from `CLAUDE.md`):
+
+> `register_settings` → `register_menu_items` / ... → `register_routes` → `on_startup` (topological order)
+
+The DB engine is created by the hosting layer **before** module hooks run, but sessions are per-request — we don't run module code against the DB during `register_settings`. Therefore:
+
+- **`register_settings`** installs `app.state.<package>.settings` populated with **pydantic defaults only**. This preserves the invariant that downstream hooks (menu, permissions, routes) can read settings.
+- **Hosting lifespan hydrates before any module `on_startup` runs.** The hosting layer (not a module) owns a "hydrate-all" step at the very start of the FastAPI lifespan: open a DB session, iterate the registered module-settings classes, reassign each `app.state.<package>.settings`, then dispatch module `on_startup` hooks. This guarantees every module sees DB-hydrated values during its own startup (important for e.g. `background_tasks` configuring Celery from `broker_url`).
+- **Request handlers** always see DB-hydrated values.
+- **Stateful handles built at boot** (SMTP client, Celery broker config, middleware `secret_key`) either (a) subscribe to `settings.reloaded` and rebuild themselves, or (b) declare `requires_restart=True` on the field — see the table below.
+
+## `requires_restart` fields
+
+| Module | Field | Why |
+|---|---|---|
+| `background_tasks` | `broker_url` | Celery worker reads this in a separate process; reload doesn't reach it |
+| `background_tasks` | `result_backend` | Same reason |
+| `users` | `cookie_secure` | Applied to `SessionMiddleware` at `add_middleware` time; Starlette middleware is frozen after `app` is built |
+| `users` | `cookie_name`, `cookie_samesite`, `cookie_max_age_seconds` | Same middleware-freeze reason |
+
+All other fields are hot-reloadable. The SMTP mailer in `users` subscribes to `settings.reloaded` and rebuilds its client on any change to `smtp_*` or `mailer` fields.
+
+Bootstrap fields (`SM_DATABASE_URL`, `SM_ENVIRONMENT`, `SM_SECRET_KEY`, `SM_VITE_DEV_URL`) don't appear in the UI — they're not in the DB.
+
+## API surface (new endpoints)
+
+Added under the existing settings router:
+
+- `GET /settings/api/modules` — list of registered modules with current hydrated values, defaults, metadata (types, enums, groups, `requires_restart`, `is_secret`). Secrets returned masked.
+- `PUT /settings/api/modules/{package}` — body `{field_name: new_value, ...}`. Validates by constructing `cls(**merged)`; on success writes deltas and fires reload. Mask sentinel on a secret field = "no change".
+- `DELETE /settings/api/modules/{package}/{field}` — clear a single override (reset to default). Triggers reload.
+
+View endpoints:
+- `GET /settings/modules` — replaces the existing read-only Inertia page. Props include the same data as the API response.
+
+## Failure modes & edge cases
+
+- **Pydantic validation fails on save.** UI shows per-field errors; no DB write; `app.state` unchanged.
+- **Pydantic validation fails during `on_startup` hydrate.** The field's DB row is bad (e.g. schema changed between releases). Log a warning, keep the default for that field, continue booting. The UI flags the field as "stored value invalid — using default".
+- **A module disappears between releases.** Its `Setting` rows become orphaned. `make doctor` gets a new `SM018` warning listing orphan settings rows; a separate CLI `sm-settings prune-orphans` removes them.
+- **Concurrent edits.** Last write wins (there's no optimistic concurrency today on `Setting`). Acceptable — admin UI with low write rate.
+- **Placeholder token-secret check.** `UsersSettings.model_validator` fires during DB hydration in production. On boot: blocks startup (matches current behavior). On UI save: returns validation error.
+
+## Migration
+
+- **No Alembic migration** — `Setting` table already exists.
+- **`sm-settings import-from-env` CLI** — one-shot: reads `SM_<MODULE>_*` from the current process environment, writes corresponding rows to `Setting` for each registered module. Idempotent.
+- **Release note** — deployments must run `sm-settings import-from-env` after upgrade (or accept that all modules revert to defaults).
+- **Per-module code changes:**
+  - Remove `env_prefix` and `env_file` from `SettingsConfigDict`.
+  - `register_settings` calls `register_module_settings(app, package, SettingsCls)`; the helper installs defaults on `app.state.<package>.settings`.
+  - Services that previously received `settings=SettingsCls()` now receive the default instance, and re-read from `app.state` on reload via the event subscription.
+- **Host-level split:**
+  - `BootstrapSettings` — the four env vars, read at boot. Lives in `framework/hosting`.
+  - `HostSettings` — `multi_tenant`, `tenant_header`, `i18n_default_locale`, `i18n_supported_locales`, `i18n_cookie_name`, plus anything else currently on the monolithic `HostingSettings` minus the bootstrap four. DB-backed via the same `register_module_settings` helper under `package="host"`.
+- **`.env.example`** — rewritten to the four bootstrap vars; everything else removed.
+- **`docker-compose.yml`** — removes `SM_BG_TASKS_BROKER_URL` / `SM_BG_TASKS_RESULT_BACKEND` environment entries; the Redis defaults in `BackgroundTasksSettings` are updated to `redis://redis:6379/*` (matching the compose Redis service hostname). Dev-outside-compose users run `sm-settings import-from-env` or set overrides in the UI.
+- **`README.md`** — env-var table shrinks to four rows + a pointer to `/settings/modules`.
+
+## Tests
+
+- **New:**
+  - `modules/settings/tests/test_store.py` — round-trip for `SettingsStore` (`set_override`, `get_overrides`, `clear_override`).
+  - `modules/settings/tests/test_hydrate.py` — `hydrate_settings` parses each `value_type` correctly; falls back to defaults; pydantic validation errors surface.
+  - `modules/settings/tests/test_module_settings_api.py` — GET/PUT/DELETE on the new endpoints; mask sentinel handling; validation error propagation.
+  - `modules/settings/tests/test_hot_reload.py` — save → `app.state.<package>.settings` is reassigned; `settings.reloaded` event fires with the right payload.
+  - `tests/test_bootstrap_settings.py` — the four bootstrap env vars load correctly; missing `SM_SECRET_KEY` fails boot with a clear message.
+- **Updated:**
+  - `modules/users/tests/test_settings.py` — tests that currently `monkeypatch.setenv("SM_USERS_*", ...)` are rewritten to write via `SettingsStore` and hydrate. The placeholder-secret production check becomes a hydrate-time test.
+  - `tests/conftest.py` — adds a `settings_store` fixture; `app` fixture gains a `settings_overrides` param so tests can preload overrides before `on_startup`.
+- **E2E:**
+  - `tests/e2e/test_settings_ui.py` — log in as admin, navigate to `/settings/modules`, toggle `users.allow_signup` to `true`, confirm `/users/register` becomes reachable without a restart.
+
+## Diagnostics
+
+- Existing `SM012` (`register_settings` overridden but nothing on `app.state.<module>`) is still emitted — the `register_module_settings` helper satisfies it automatically.
+- New `SM018` — orphan `Setting` rows for packages that no longer register a BaseSettings class. Warning level; fixable via `sm-settings prune-orphans`.
+
+## Ship criteria
+
+- `make test` green.
+- `make lint` green, including the 300-line file cap. `_module_settings.py` is ~153 lines today; the metadata extensions should stay under the cap or split into a sibling module.
+- `make doctor` green.
+- Manual: `/settings/modules` renders, editing `users.allow_signup` takes effect without restart, editing `background_tasks.broker_url` shows the "requires restart" badge.
+- `sm-settings import-from-env` run against a dev `.env` successfully populates the `Setting` table.
+
+## Open decisions (to resolve during plan writing)
+
+- Exact shape of the `json_schema_extra` metadata conventions — may land as a small helper (`module_field(...)` wrapping `Field`) to keep module code readable.
+- Whether `settings.reloaded` events are sync or async on the bus. If the bus is already async, follow that; otherwise punt to sync with a TODO.
+- Whether `list_packages` iterates the registry or reads distinct `package` values from `Setting`. Registry is faster and is the source of truth during the app's lifetime; DB-scan is needed for `prune-orphans`.
diff --git a/framework/hosting/simple_module_hosting/_hydrate_step.py b/framework/hosting/simple_module_hosting/_hydrate_step.py
new file mode 100644
index 00000000..68070f25
--- /dev/null
+++ b/framework/hosting/simple_module_hosting/_hydrate_step.py
@@ -0,0 +1,39 @@
+"""Hydrate every registered module's settings from the DB at lifespan start.
+
+Runs before any module ``on_startup`` hook so startup code sees DB-backed
+values. ``importlib`` is used to resolve plugin names lazily so the
+framework→plugin AST check (SM009) stays clean.
+"""
+
+from __future__ import annotations
+
+import importlib
+import logging
+from typing import Any
+
+from fastapi import FastAPI
+
+logger = logging.getLogger(__name__)
+
+_MODULE_PACKAGE = "settings"
+
+
+async def hydrate_all(app: FastAPI, store: Any) -> None:
+    """Resolve every registered module's settings from the DB."""
+    settings_services = getattr(app.state, _MODULE_PACKAGE, None)
+    if settings_services is None:
+        return
+
+    hydrate_settings = importlib.import_module("settings.hydrate").hydrate_settings
+
+    for package, cls in settings_services.module_registry.items():
+        try:
+            hydrated = await hydrate_settings(cls, store, package)
+        except Exception:
+            logger.exception("Hydrating %s failed; falling back to defaults", package)
+            continue
+        services = getattr(app.state, package, None)
+        if services is None:
+            logger.warning("app.state.%s missing during hydrate — skipping", package)
+            continue
+        services.settings = hydrated
diff --git a/framework/hosting/simple_module_hosting/app_builder.py b/framework/hosting/simple_module_hosting/app_builder.py
index b00b4f52..a59754a0 100644
--- a/framework/hosting/simple_module_hosting/app_builder.py
+++ b/framework/hosting/simple_module_hosting/app_builder.py
@@ -152,6 +152,20 @@ def create_app(settings: Settings | None = None) -> FastAPI:
     async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
         app.state.migration = await check_migrations(app.state.sm.db.engine)
 
+        # Hydrate all registered settings from DB before any module
+        # on_startup hook runs, so startup code sees DB-backed values.
+        # Importlib keeps plugin names out of the framework AST (SM009).
+        if hasattr(app.state, "settings"):
+            import importlib
+
+            from simple_module_hosting._hydrate_step import hydrate_all
+
+            service_cls = importlib.import_module("settings.service").SettingService
+            store_cls = importlib.import_module("settings.store").SettingsStore
+
+            async with app.state.sm.db.session_factory() as session:
+                await hydrate_all(app, store_cls(service_cls(session)))
+
         for mod in modules:
             await mod.on_startup(app)
         yield
@@ -171,6 +185,33 @@ async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
     for mod in modules:
         mod.register_settings(app)
 
+    # Register host-level settings under package="host" (DB-backed). The
+    # Settings module must already have run register_settings (topo order
+    # puts it early; its meta.depends_on = [] so it's among the first).
+    # When the Settings module isn't enabled, there's no registry to
+    # register against — skip quietly.
+    #
+    # We resolve `settings.registration` via importlib rather than a plain
+    # `from settings.registration import ...`: the SM009 coupling check is
+    # AST-based and forbids any static import of a plugin package name
+    # from within framework/* code. Dynamic resolution keeps the framework
+    # AST plugin-free while still hitting the real helper at runtime.
+    if hasattr(app.state, "settings"):
+        import importlib
+        from dataclasses import dataclass as _dataclass
+
+        from simple_module_hosting.host_settings import HostSettings
+
+        _register_module_settings = importlib.import_module(
+            "settings.registration"
+        ).register_module_settings
+
+        @_dataclass
+        class _HostServices:
+            settings: HostSettings
+
+        _register_module_settings(app, "host", HostSettings, lambda s: _HostServices(settings=s))
+
     if settings.is_development:
         settings_diagnostics = check_settings_registration(app, modules)
         if settings_diagnostics:
diff --git a/framework/hosting/simple_module_hosting/bootstrap_settings.py b/framework/hosting/simple_module_hosting/bootstrap_settings.py
new file mode 100644
index 00000000..ef7048cf
--- /dev/null
+++ b/framework/hosting/simple_module_hosting/bootstrap_settings.py
@@ -0,0 +1,55 @@
+"""Env-only settings read before the database is available.
+
+Everything here is needed either to connect to the DB, sign session cookies,
+or configure the Python process (logging, Vite asset URLs, module allowlist).
+These values stay in ``.env`` — all other settings live in the DB.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import model_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from simple_module_core.environments import NON_PROD_ENVIRONMENTS
+
+_PLACEHOLDER_SECRET_KEY = "change-me-in-production"
+
+
+class BootstrapSettings(BaseSettings):
+    """Pre-DB bootstrap environment knobs."""
+
+    model_config = SettingsConfigDict(env_prefix="SM_", env_file=".env", extra="ignore")
+
+    database_url: str = "sqlite+aiosqlite:///./app.db"
+    db_pool_size: int = 10
+    db_max_overflow: int = 20
+    db_pool_pre_ping: bool = True
+    db_pool_recycle: int = 1800
+
+    environment: str = "development"
+    secret_key: str = _PLACEHOLDER_SECRET_KEY
+    vite_dev_url: str = "http://localhost:5050"
+    debug: bool = False
+
+    log_level: str = "INFO"
+    log_format: Literal["json", "text"] = "json"
+
+    modules_enabled: list[str] | None = None
+
+    @property
+    def is_development(self) -> bool:
+        return self.environment == "development"
+
+    @model_validator(mode="after")
+    def _forbid_placeholder_secret_in_production(self) -> BootstrapSettings:
+        if (
+            self.environment not in NON_PROD_ENVIRONMENTS
+            and self.secret_key == _PLACEHOLDER_SECRET_KEY
+        ):
+            raise ValueError(
+                f"SM_SECRET_KEY must be set to a non-default value when "
+                f"SM_ENVIRONMENT={self.environment!r}. Generate one with "
+                "`python -c 'import secrets; print(secrets.token_urlsafe(48))'`."
+            )
+        return self
diff --git a/framework/hosting/simple_module_hosting/host_settings.py b/framework/hosting/simple_module_hosting/host_settings.py
new file mode 100644
index 00000000..779d9071
--- /dev/null
+++ b/framework/hosting/simple_module_hosting/host_settings.py
@@ -0,0 +1,33 @@
+"""Host-level settings stored in the DB (not env).
+
+Registered under ``package="host"`` so the UI shows them alongside module
+settings. The hosting layer still reads these directly from
+``app.state.host.settings``.
+"""
+
+from __future__ import annotations
+
+from pydantic import model_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class HostSettings(BaseSettings):
+    """DB-backed host configuration — defaults live here, overrides in DB."""
+
+    model_config = SettingsConfigDict(extra="ignore")
+
+    multi_tenant: bool = False
+    tenant_header: str = ""
+
+    i18n_default_locale: str = "en"
+    i18n_supported_locales: list[str] = ["en"]
+    i18n_cookie_name: str = "locale"
+
+    @model_validator(mode="after")
+    def _check_default_locale_supported(self) -> HostSettings:
+        if self.i18n_default_locale not in self.i18n_supported_locales:
+            raise ValueError(
+                f"i18n_default_locale '{self.i18n_default_locale}' is not in "
+                f"i18n_supported_locales {self.i18n_supported_locales}"
+            )
+        return self
diff --git a/framework/hosting/simple_module_hosting/settings.py b/framework/hosting/simple_module_hosting/settings.py
index c0ee6863..33bd8fbe 100644
--- a/framework/hosting/simple_module_hosting/settings.py
+++ b/framework/hosting/simple_module_hosting/settings.py
@@ -1,103 +1,10 @@
-"""Application settings loaded from environment variables."""
+"""Back-compat shim — prefer BootstrapSettings + HostSettings directly."""
 
-from typing import Literal
+from __future__ import annotations
 
-from pydantic import model_validator
-from pydantic_settings import BaseSettings, SettingsConfigDict
-from simple_module_core.environments import NON_PROD_ENVIRONMENTS
+from simple_module_hosting.bootstrap_settings import BootstrapSettings
+from simple_module_hosting.host_settings import HostSettings
 
-_PLACEHOLDER_SECRET_KEY = "change-me-in-production"
 
-
-class Settings(BaseSettings):
-    """Configuration for the SimpleModule host application.
-
-    All settings can be overridden via environment variables prefixed with ``SM_``.
-    """
-
-    model_config = SettingsConfigDict(env_prefix="SM_", env_file=".env", extra="ignore")
-
-    # Database
-    database_url: str = "sqlite+aiosqlite:///./app.db"
-
-    # Connection pool — server-side providers only (Postgres); SQLite ignores these.
-    db_pool_size: int = 10
-    db_max_overflow: int = 20
-    db_pool_pre_ping: bool = True
-    db_pool_recycle: int = 1800  # 30 minutes — matches common proxy idle-timeouts
-
-    # App
-    environment: str = "development"
-    secret_key: str = "change-me-in-production"
-    vite_dev_url: str = "http://localhost:5050"
-    debug: bool = False
-
-    # Logging
-    log_level: str = "INFO"
-    log_format: Literal["json", "text"] = "json"
-
-    # Module loading
-    modules_enabled: list[str] | None = None
-    """Optional allowlist of module names to load.
-
-    When ``None`` (default), every installed module is loaded. When a list is
-    provided (e.g. ``SM_MODULES_ENABLED='["Auth","Products"]'`` in env), only
-    those modules are loaded — useful for staging rollouts, feature flags at
-    the module level, or debugging isolation. Names are matched case-insensitively
-    against ``ModuleMeta.name``.
-    """
-
-    # Multi-tenancy — opt-in. When ``False`` the tenant middleware is not
-    # installed, so MultiTenantMixin queries are not auto-filtered. Turn
-    # it on only for deployments that actually partition data by tenant.
-    multi_tenant: bool = False
-
-    # Header used to resolve the active tenant when there's no
-    # authenticated user. Empty string disables the header source
-    # entirely — useful in production to force tenant resolution through
-    # the auth token only.
-    tenant_header: str = ""
-
-    # Internationalization
-    i18n_default_locale: str = "en"
-    """Locale used when no cookie, Accept-Language, or supported locale match."""
-
-    i18n_supported_locales: list[str] = ["en"]
-    """Locales the host will serve. Must include i18n_default_locale.
-
-    Set via env as JSON-style list, e.g. ``SM_I18N_SUPPORTED_LOCALES='["en","es"]'``.
-    """
-
-    i18n_cookie_name: str = "locale"
-    """Name of the cookie that overrides browser Accept-Language."""
-
-    @property
-    def is_development(self) -> bool:
-        return self.environment == "development"
-
-    @model_validator(mode="after")
-    def _check_default_locale_supported(self) -> "Settings":
-        if self.i18n_default_locale not in self.i18n_supported_locales:
-            raise ValueError(
-                f"i18n_default_locale '{self.i18n_default_locale}' is not in "
-                f"i18n_supported_locales {self.i18n_supported_locales}"
-            )
-        return self
-
-    @model_validator(mode="after")
-    def _forbid_placeholder_secret_in_production(self) -> "Settings":
-        """Fail boot if production is running with the placeholder secret key.
-
-        Session cookies and any other itsdangerous-signed payloads are signed
-        with ``secret_key``; a known default would let anyone forge them.
-        """
-        if (
-            self.environment not in NON_PROD_ENVIRONMENTS
-            and self.secret_key == _PLACEHOLDER_SECRET_KEY
-        ):
-            raise ValueError(
-                f"SM_SECRET_KEY must be set to a non-default value when "
-                f"SM_ENVIRONMENT={self.environment!r}. Generate one with "
-                "`python -c 'import secrets; print(secrets.token_urlsafe(48))'`."
-            )
-        return self
+class Settings(HostSettings, BootstrapSettings):
+    """Combined bootstrap + host settings for legacy import sites."""
diff --git a/modules/background_tasks/background_tasks/module.py b/modules/background_tasks/background_tasks/module.py
index c54a4acd..d1f91050 100644
--- a/modules/background_tasks/background_tasks/module.py
+++ b/modules/background_tasks/background_tasks/module.py
@@ -43,11 +43,25 @@ class BackgroundTasksModule(ModuleBase):
     )
 
     def register_settings(self, app: FastAPI) -> None:
+        import importlib
+
         from background_tasks.services import BackgroundTasksServices
         from background_tasks.settings import BackgroundTasksSettings
 
-        services = BackgroundTasksServices(settings=BackgroundTasksSettings())
-        app.state.background_tasks = services
+        # SM009 is AST-based: a static `from settings.registration import ...`
+        # from a module helper is fine (plugin→plugin), but we resolve via
+        # importlib here to match the convention used framework-side and to
+        # keep the dependency direction one-way explicit.
+        register_module_settings = importlib.import_module(
+            "settings.registration"
+        ).register_module_settings
+
+        register_module_settings(
+            app,
+            "background_tasks",
+            BackgroundTasksSettings,
+            lambda s: BackgroundTasksServices(settings=s),
+        )
 
     def register_permissions(self, registry: PermissionRegistry) -> None:
         registry.add_group(PERM_GROUP, [PERM_VIEW, PERM_MANAGE])
diff --git a/modules/background_tasks/background_tasks/settings.py b/modules/background_tasks/background_tasks/settings.py
index 07521744..bfe03a0e 100644
--- a/modules/background_tasks/background_tasks/settings.py
+++ b/modules/background_tasks/background_tasks/settings.py
@@ -1,10 +1,26 @@
-"""BackgroundTasks module settings loaded from SM_BG_TASKS_* env vars."""
+"""BackgroundTasks module settings (DB-backed).
+
+Construction no longer reads ``SM_BG_TASKS_*`` environment variables. Values
+come from pydantic defaults at boot, then get hydrated from the DB by the
+hosting lifespan before module ``on_startup`` runs. Runtime changes go
+through ``settings.reload.apply_changes_and_reload``.
+
+The one remaining env read is ``SM_ENVIRONMENT``, consulted by the
+``@model_validator`` to refuse a localhost broker in production — that's a
+host-level setting, not a background_tasks-module field.
+
+The Celery-critical fields (``broker_url``, ``result_backend``,
+``task_default_queue``) are marked ``requires_restart=True`` via
+``json_schema_extra`` because workers read these once at process start, so
+DB changes can't be hot-reloaded: the admin UI should surface that bumping
+these values requires a worker restart.
+"""
 
 from __future__ import annotations
 
 import os
 
-from pydantic import model_validator
+from pydantic import Field, model_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 from simple_module_core.environments import NON_PROD_ENVIRONMENTS
 
@@ -17,18 +33,19 @@
     DEFAULT_RETENTION_DAYS,
     DEFAULT_STUCK_AFTER_SECONDS,
     DEFAULT_STUCK_SWEEP_INTERVAL_SECONDS,
-    ENV_PREFIX,
 )
 
+_CELERY_RESTART = {"requires_restart": True, "group": "Celery"}
+
 
 class BackgroundTasksSettings(BaseSettings):
     """Configuration for the Celery + Redis task runner."""
 
-    model_config = SettingsConfigDict(env_prefix=ENV_PREFIX, env_file=".env", extra="ignore")
+    model_config = SettingsConfigDict(extra="ignore")
 
-    broker_url: str = DEFAULT_BROKER_URL
-    result_backend: str = DEFAULT_RESULT_BACKEND
-    task_default_queue: str = DEFAULT_QUEUE
+    broker_url: str = Field(default=DEFAULT_BROKER_URL, json_schema_extra=_CELERY_RESTART)
+    result_backend: str = Field(default=DEFAULT_RESULT_BACKEND, json_schema_extra=_CELERY_RESTART)
+    task_default_queue: str = Field(default=DEFAULT_QUEUE, json_schema_extra=_CELERY_RESTART)
 
     # A task that has been ``running`` longer than this without a heartbeat is
     # flipped to ``stuck`` by the beat sweep. 5 min is long enough to cover
@@ -54,9 +71,9 @@ def _forbid_localhost_broker_in_production(self) -> BackgroundTasksSettings:
             return self
         bad = []
         if "localhost" in self.broker_url or "127.0.0.1" in self.broker_url:
-            bad.append(f"{ENV_PREFIX}BROKER_URL")
+            bad.append("broker_url")
         if "localhost" in self.result_backend or "127.0.0.1" in self.result_backend:
-            bad.append(f"{ENV_PREFIX}RESULT_BACKEND")
+            bad.append("result_backend")
         if bad:
             names = ", ".join(bad)
             raise ValueError(
diff --git a/modules/datasets/datasets/module.py b/modules/datasets/datasets/module.py
index faf4a860..fc916d7b 100644
--- a/modules/datasets/datasets/module.py
+++ b/modules/datasets/datasets/module.py
@@ -35,10 +35,25 @@ class DatasetsModule(ModuleBase):
     )
 
     def register_settings(self, app: FastAPI) -> None:
+        import importlib
+
         from datasets.services import DatasetsServices
         from datasets.settings import DatasetsSettings
 
-        app.state.datasets = DatasetsServices(settings=DatasetsSettings())
+        # SM009 is AST-based: a static `from settings.registration import ...`
+        # from a module helper is fine (plugin→plugin), but we resolve via
+        # importlib here to match the convention used framework-side and to
+        # keep the dependency direction one-way explicit.
+        register_module_settings = importlib.import_module(
+            "settings.registration"
+        ).register_module_settings
+
+        register_module_settings(
+            app,
+            "datasets",
+            DatasetsSettings,
+            lambda s: DatasetsServices(settings=s),
+        )
 
     def register_routes(self, api_router: APIRouter, view_router: APIRouter) -> None:
         from datasets.endpoints.api import router as api
@@ -128,7 +143,8 @@ def _setting_definitions() -> list[SettingDefinition]:
             default=str(constants.DEFAULT_MAX_UPLOAD_MB),
             description=(
                 "Per-dataset upload size cap in megabytes. Overrides the "
-                "``SM_DATASETS_MAX_UPLOAD_MB`` env default at runtime."
+                "pydantic default on ``DatasetsSettings.max_upload_mb`` at "
+                "runtime."
             ),
             value_type=SettingValueType.INT,
         ),
diff --git a/modules/datasets/datasets/settings.py b/modules/datasets/datasets/settings.py
index 0c86136b..ab0a9806 100644
--- a/modules/datasets/datasets/settings.py
+++ b/modules/datasets/datasets/settings.py
@@ -1,8 +1,13 @@
-"""Datasets module settings loaded from SM_DATASETS_* environment variables.
+"""Datasets module settings (DB-backed).
 
-Bytes storage is delegated to the ``file_storage`` module — its
-``SM_FILE_STORAGE_*`` variables (backend, FS root, S3 bucket, etc.) are
-the single source of truth. Datasets owns only its catalog-specific knobs.
+Construction no longer reads ``SM_DATASETS_*`` environment variables.
+Values come from pydantic defaults at boot, then get hydrated from the DB
+by the hosting lifespan before module ``on_startup`` runs. Runtime changes
+go through ``settings.reload.apply_changes_and_reload``.
+
+Bytes storage is delegated to the ``file_storage`` module — its own
+settings (backend, FS root, S3 bucket, etc.) are the single source of
+truth. Datasets owns only its catalog-specific knobs.
 """
 
 from __future__ import annotations
@@ -16,11 +21,7 @@
 class DatasetsSettings(BaseSettings):
     """Configuration for the datasets catalog."""
 
-    model_config = SettingsConfigDict(
-        env_prefix=constants.ENV_PREFIX,
-        env_file=".env",
-        extra="ignore",
-    )
+    model_config = SettingsConfigDict(extra="ignore")
 
     max_upload_mb: int = Field(
         default=constants.DEFAULT_MAX_UPLOAD_MB,
diff --git a/modules/datasets/tests/test_tasks.py b/modules/datasets/tests/test_tasks.py
index 7996b4da..653293cc 100644
--- a/modules/datasets/tests/test_tasks.py
+++ b/modules/datasets/tests/test_tasks.py
@@ -2,9 +2,12 @@
 
 The task runs in a Celery worker — its DB goes through
 ``background_tasks.sync_db`` (sync engine reading ``SM_DATABASE_URL``)
-and its bytes come from ``file_storage.build_backend`` (which re-reads
-``SM_FILE_STORAGE_*`` env). Both are independent of the async test
-``app`` fixture, so each test points them at tmp paths for isolation.
+and its bytes come from ``file_storage.build_backend`` (which builds
+from ``FileStorageSettings()``, pydantic defaults). Both are independent
+of the async test ``app`` fixture, so each test points them at tmp paths
+for isolation: ``SM_DATABASE_URL`` via env (still host-level) and the
+storage root by monkeypatching ``FileStorageSettings`` to pre-fill the
+``fs_root_path`` kwarg.
 """
 
 from __future__ import annotations
@@ -42,14 +45,27 @@ def _isolate_worker_env(
     """
     from background_tasks import sync_db
     from datasets.models import Dataset as _Dataset
+    from file_storage import settings as fs_settings
+    from file_storage.settings import FileStorageSettings as _RealFileStorageSettings
 
     db_file = tmp_path / "worker.db"
     fs_root = tmp_path / "fs"
     fs_root.mkdir()
 
     monkeypatch.setenv("SM_DATABASE_URL", f"sqlite:///{db_file}")
-    monkeypatch.setenv("SM_FILE_STORAGE_BACKEND", "filesystem")
-    monkeypatch.setenv("SM_FILE_STORAGE_FS_ROOT_PATH", str(fs_root))
+
+    # The worker (``datasets.tasks._download_to_tempfile``) constructs
+    # ``FileStorageSettings()`` with no args — pydantic defaults only, no
+    # env reads any more. Swap in a factory that pre-fills the tmp root so
+    # the worker sees this test's filesystem backend without a shared DB.
+    def _factory(**kwargs: object) -> _RealFileStorageSettings:
+        return _RealFileStorageSettings(
+            backend="filesystem",
+            fs_root_path=str(fs_root),
+            **kwargs,
+        )
+
+    monkeypatch.setattr(fs_settings, "FileStorageSettings", _factory)
 
     # Reset the process-global sync engine so the new URL is picked up.
     sync_db._engine = None
diff --git a/modules/file_storage/file_storage/backends/s3.py b/modules/file_storage/file_storage/backends/s3.py
index b8b5057d..e177cc2d 100644
--- a/modules/file_storage/file_storage/backends/s3.py
+++ b/modules/file_storage/file_storage/backends/s3.py
@@ -142,10 +142,7 @@ def _is_not_found(exc: Exception) -> bool:
 @register_backend(constants.BackendId.S3)
 def _build(settings: FileStorageSettings) -> S3Backend:
     if not settings.s3_bucket or not settings.s3_region:
-        raise ConfigurationError(
-            f"S3 backend requires {constants.ENV_PREFIX}S3_BUCKET and "
-            f"{constants.ENV_PREFIX}S3_REGION."
-        )
+        raise ConfigurationError("S3 backend requires s3_bucket and s3_region.")
     client_kwargs: dict[str, Any] = {"region_name": settings.s3_region}
     if settings.s3_endpoint_url:
         client_kwargs["endpoint_url"] = settings.s3_endpoint_url
diff --git a/modules/file_storage/file_storage/module.py b/modules/file_storage/file_storage/module.py
index d428b9d8..42ff6640 100644
--- a/modules/file_storage/file_storage/module.py
+++ b/modules/file_storage/file_storage/module.py
@@ -26,16 +26,31 @@ class FileStorageModule(ModuleBase):
         name=constants.MODULE_PASCAL,
         route_prefix=constants.ROUTE_PREFIX_API,
         view_prefix=constants.ROUTE_PREFIX_VIEW,
+        # Needs Settings to run first so register_module_settings can reach
+        # app.state.settings.module_registry during register_settings.
+        depends_on=["Settings"],
     )
 
     def register_settings(self, app: FastAPI) -> None:
-        from file_storage.backends import build_backend
+        import importlib
+
         from file_storage.services import FileStorageServices
         from file_storage.settings import FileStorageSettings
 
-        settings = FileStorageSettings()
-        backend = build_backend(settings)
-        app.state.file_storage = FileStorageServices(settings=settings, backend=backend)
+        # SM009 is AST-based: a static `from settings.registration import ...`
+        # from a module helper is fine (plugin→plugin), but we resolve via
+        # importlib here to match the convention used framework-side and to
+        # keep the dependency direction one-way explicit.
+        register_module_settings = importlib.import_module(
+            "settings.registration"
+        ).register_module_settings
+
+        register_module_settings(
+            app,
+            "file_storage",
+            FileStorageSettings,
+            lambda s: FileStorageServices(settings=s),
+        )
 
     def register_routes(self, api_router: APIRouter, view_router: APIRouter) -> None:
         from file_storage.endpoints.api import router as api
@@ -89,9 +104,18 @@ def locale_dirs(self) -> dict[str, Path]:
         return {constants.LOCALE_NAMESPACE: base}
 
     async def on_startup(self, app: FastAPI) -> None:
-        """Ensure the filesystem backend's root exists; probe S3 bucket reachability."""
+        """Build the storage backend and probe its backing resource.
+
+        Backend construction is deferred to ``on_startup`` so settings
+        hydrated from the DB (between ``register_settings`` and here) are
+        picked up — constructing in ``register_settings`` would bake in
+        the pydantic defaults instead of the DB overrides.
+        """
+        from file_storage.backends import build_backend
+
         services = app.state.file_storage
         settings = services.settings
+        services.backend = build_backend(settings)
         if settings.backend == constants.BackendId.FILESYSTEM:
             root = settings.resolved_fs_root()
             root.mkdir(parents=True, exist_ok=True)
diff --git a/modules/file_storage/file_storage/services.py b/modules/file_storage/file_storage/services.py
index 63160020..d69609df 100644
--- a/modules/file_storage/file_storage/services.py
+++ b/modules/file_storage/file_storage/services.py
@@ -5,7 +5,9 @@
 
 Holds the resolved :class:`StorageBackend` so endpoints don't reconstruct it
 per request — provider handles (S3 client sessions, open file descriptors)
-are pooled inside the backend instance.
+are pooled inside the backend instance. ``backend`` is populated in
+``on_startup`` (after settings have been hydrated from the DB), so it's
+optional at construction time.
 """
 
 from __future__ import annotations
@@ -23,4 +25,4 @@ class FileStorageServices:
     """file_storage module singletons. Single slot at ``app.state.file_storage``."""
 
     settings: FileStorageSettings
-    backend: StorageBackend
+    backend: StorageBackend | None = None
diff --git a/modules/file_storage/file_storage/settings.py b/modules/file_storage/file_storage/settings.py
index 2c0215e1..82e913e1 100644
--- a/modules/file_storage/file_storage/settings.py
+++ b/modules/file_storage/file_storage/settings.py
@@ -1,4 +1,13 @@
-"""file_storage settings loaded from SM_FILE_STORAGE_* environment variables."""
+"""file_storage module settings (DB-backed).
+
+Construction no longer reads ``SM_FILE_STORAGE_*`` environment variables.
+Values come from pydantic defaults at boot, then get hydrated from the DB
+by the hosting lifespan before module ``on_startup`` runs. Runtime changes
+go through ``settings.reload.apply_changes_and_reload``.
+
+Fields are grouped via ``json_schema_extra={"group": ...}`` so the admin UI
+can render them under their respective backend sections.
+"""
 
 from __future__ import annotations
 
@@ -17,27 +26,33 @@ class FileStorageSettings(BaseSettings):
     backend registry). All ``s3_*`` fields are optional unless ``backend``
     selects S3, in which case the validator below enforces presence of
     bucket + region. Custom backends supply their own validation by
-    subclassing or by reading additional env vars at registration time.
+    subclassing or by reading additional fields at registration time.
     """
 
-    model_config = SettingsConfigDict(
-        env_prefix=constants.ENV_PREFIX,
-        env_file=".env",
-        extra="ignore",
-    )
+    model_config = SettingsConfigDict(extra="ignore")
 
     backend: str = constants.DEFAULT_BACKEND
 
     # Filesystem backend
-    fs_root_path: str = constants.DEFAULT_FS_ROOT
+    fs_root_path: str = Field(
+        default=constants.DEFAULT_FS_ROOT,
+        json_schema_extra={"group": "Filesystem"},
+    )
 
     # S3-compatible backend (works with AWS S3, MinIO, R2, etc.)
-    s3_bucket: str = ""
-    s3_region: str = ""
-    s3_access_key_id: str = ""
-    s3_secret_access_key: str = ""
-    s3_endpoint_url: str = ""  # custom endpoint for MinIO / R2
-    s3_presign_ttl_seconds: int = constants.DEFAULT_PRESIGN_TTL_SECONDS
+    s3_bucket: str = Field(default="", json_schema_extra={"group": "S3"})
+    s3_region: str = Field(default="", json_schema_extra={"group": "S3"})
+    s3_access_key_id: str = Field(default="", json_schema_extra={"group": "S3"})
+    s3_secret_access_key: str = Field(default="", json_schema_extra={"group": "S3"})
+    s3_endpoint_url: str = Field(
+        default="",
+        json_schema_extra={"group": "S3"},
+        description="Custom endpoint for MinIO / R2. Blank uses AWS default.",
+    )
+    s3_presign_ttl_seconds: int = Field(
+        default=constants.DEFAULT_PRESIGN_TTL_SECONDS,
+        json_schema_extra={"group": "S3"},
+    )
 
     # Limits
     max_file_size_bytes: int = constants.DEFAULT_MAX_FILE_SIZE_BYTES
@@ -58,8 +73,8 @@ def _validate_backend_config(self) -> FileStorageSettings:
             missing = [
                 name
                 for name, value in (
-                    (f"{constants.ENV_PREFIX}S3_BUCKET", self.s3_bucket),
-                    (f"{constants.ENV_PREFIX}S3_REGION", self.s3_region),
+                    ("s3_bucket", self.s3_bucket),
+                    ("s3_region", self.s3_region),
                 )
                 if not value
             ]
diff --git a/modules/settings/pyproject.toml b/modules/settings/pyproject.toml
index add7897b..95bc19f4 100644
--- a/modules/settings/pyproject.toml
+++ b/modules/settings/pyproject.toml
@@ -13,6 +13,9 @@ dependencies = [
 [project.entry-points.simple_module]
 settings = "settings.module:SettingsModule"
 
+[project.scripts]
+sm-settings = "settings.cli:main"
+
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"
diff --git a/modules/settings/settings/_module_settings.py b/modules/settings/settings/_module_settings.py
index 2b7fc190..39c7e148 100644
--- a/modules/settings/settings/_module_settings.py
+++ b/modules/settings/settings/_module_settings.py
@@ -1,14 +1,7 @@
 """Autodiscover per-module pydantic ``BaseSettings`` attached to ``app.state``.
 
-Framework convention (see ``CLAUDE.md`` and ``ModuleBase.register_settings``):
-each module stores a services dataclass on ``app.state.<package_name>`` whose
-``.settings`` attribute is a pydantic ``BaseSettings`` subclass. This helper
-walks ``app.state.sm.modules``, derives the package name from
-``type(mod).__module__``, pulls the settings object off the attached services,
-and returns a serializable view for the admin UI.
-
-Fields whose name matches ``_SECRET_PATTERNS`` are masked in the output so
-secrets never reach the browser even read-only.
+Each module stores a services dataclass on ``app.state.<package>`` whose
+``.settings`` attribute is a pydantic ``BaseSettings`` subclass.
 """
 
 from __future__ import annotations
@@ -20,15 +13,21 @@
 from fastapi import FastAPI
 from pydantic_settings import BaseSettings
 
-# Case-insensitive fragment match. We intentionally DON'T match the bare word
-# "token" (would mask `verification_token_lifetime_seconds` — just an int) or
-# "key" alone (would mask `s3_bucket_key_prefix` etc.). Instead we require a
-# marker that actually indicates material: "password", "secret", "api_key",
-# "private_key", or the composite "token_secret" used by fastapi-users.
+from settings.env_vars import env_prefix_for
+from settings.hydrate import value_type_for_field
+
+# We intentionally DON'T match the bare word "token" (would mask
+# `verification_token_lifetime_seconds` — just an int) or "key" alone (would
+# mask `s3_bucket_key_prefix`). Only fragments that actually indicate material.
 _SECRET_PATTERNS = re.compile(
     r"(password|secret|api[_-]?key|private[_-]?key|token[_-]?secret)", re.I
 )
-_SECRET_MASK = "••••••••"
+SECRET_MASK = "••••••••"
+
+
+def is_secret_field(name: str) -> bool:
+    """True if a field name suggests it holds credential material."""
+    return bool(_SECRET_PATTERNS.search(name))
 
 
 @dataclass(frozen=True, slots=True)
@@ -39,6 +38,9 @@ class ModuleSettingField:
     default: Any
     description: str
     is_secret: bool
+    type: str
+    requires_restart: bool
+    group: str | None
 
 
 @dataclass(frozen=True, slots=True)
@@ -53,24 +55,11 @@ class ModuleSettingsView:
 def _mask(value: Any) -> Any:
     if value in (None, "", [], {}):
         return value
-    return _SECRET_MASK
-
-
-def _env_prefix_of(settings: BaseSettings) -> str:
-    cfg = getattr(settings, "model_config", None)
-    if isinstance(cfg, dict):
-        return str(cfg.get("env_prefix", "") or "")
-    return str(getattr(cfg, "env_prefix", "") or "")
+    return SECRET_MASK
 
 
 def _package_of(mod: Any) -> str:
-    """Return the top-level package name of a module instance (e.g. "users").
-
-    ``type(mod).__module__`` is typically ``"<pkg>.module"`` — take the first
-    segment.
-    """
-    dotted = type(mod).__module__
-    return dotted.split(".", 1)[0]
+    return type(mod).__module__.split(".", 1)[0]
 
 
 def _extract_settings(app: FastAPI, package: str) -> BaseSettings | None:
@@ -89,45 +78,70 @@ def _extract_settings(app: FastAPI, package: str) -> BaseSettings | None:
 
 
 def _field_view(name: str, settings: BaseSettings, prefix: str) -> ModuleSettingField:
-    info = type(settings).model_fields[name]
+    cls = type(settings)
+    info = cls.model_fields[name]
     raw_value = getattr(settings, name)
-    is_secret = bool(_SECRET_PATTERNS.search(name))
+    secret = is_secret_field(name)
+    extra = info.json_schema_extra if isinstance(info.json_schema_extra, dict) else {}
     return ModuleSettingField(
         name=name,
         env_var=f"{prefix}{name.upper()}",
-        value=_mask(raw_value) if is_secret else raw_value,
-        default=_mask(info.default) if is_secret else info.default,
+        value=_mask(raw_value) if secret else raw_value,
+        default=_mask(info.default) if secret else info.default,
         description=info.description or "",
-        is_secret=is_secret,
+        is_secret=secret,
+        type=value_type_for_field(cls, name),
+        requires_restart=bool(extra.get("requires_restart", False)),
+        group=extra.get("group"),
     )
 
 
 def collect_module_settings(app: FastAPI) -> list[ModuleSettingsView]:
-    """Return a sorted, serializable view of every module's BaseSettings."""
+    """Return a sorted, serializable view of every module's BaseSettings.
+
+    Folds in both ``app.state.sm.modules`` (plugin modules) and additional
+    packages registered via ``app.state.settings.module_registry`` (e.g.
+    ``"host"``) that aren't backed by a ``ModuleBase`` instance.
+    """
     views: list[ModuleSettingsView] = []
-    modules = getattr(app.state.sm, "modules", ())
-    for mod in modules:
+    seen: set[str] = set()
+
+    for mod in getattr(app.state.sm, "modules", ()):
         package = _package_of(mod)
         settings = _extract_settings(app, package)
         if settings is None:
             continue
-        fields = [
-            _field_view(name, settings, _env_prefix_of(settings))
-            for name in type(settings).model_fields
-        ]
-        views.append(
-            ModuleSettingsView(
-                module_name=mod.meta.name,
-                package=package,
-                env_prefix=_env_prefix_of(settings),
-                class_name=type(settings).__name__,
-                fields=fields,
-            )
-        )
+        views.append(_build_view(mod.meta.name, package, settings))
+        seen.add(package)
+
+    settings_services = getattr(app.state, "settings", None)
+    registry = getattr(settings_services, "module_registry", None)
+    if registry is not None:
+        for package in registry.all_packages():
+            if package in seen:
+                continue
+            settings = _extract_settings(app, package)
+            if settings is None:
+                continue
+            views.append(_build_view(package.title(), package, settings))
+            seen.add(package)
+
     views.sort(key=lambda v: v.module_name)
     return views
 
 
+def _build_view(module_name: str, package: str, settings: BaseSettings) -> ModuleSettingsView:
+    prefix = env_prefix_for(package)
+    fields = [_field_view(name, settings, prefix) for name in type(settings).model_fields]
+    return ModuleSettingsView(
+        module_name=module_name,
+        package=package,
+        env_prefix=prefix,
+        class_name=type(settings).__name__,
+        fields=fields,
+    )
+
+
 def serialize(views: list[ModuleSettingsView]) -> list[dict[str, Any]]:
     """Convert dataclass views to plain dicts for Inertia props."""
     return [
@@ -144,6 +158,9 @@ def serialize(views: list[ModuleSettingsView]) -> list[dict[str, Any]]:
                     "default": f.default,
                     "description": f.description,
                     "is_secret": f.is_secret,
+                    "type": f.type,
+                    "requires_restart": f.requires_restart,
+                    "group": f.group,
                 }
                 for f in v.fields
             ],
diff --git a/modules/settings/settings/cli.py b/modules/settings/settings/cli.py
new file mode 100644
index 00000000..eff67039
--- /dev/null
+++ b/modules/settings/settings/cli.py
@@ -0,0 +1,78 @@
+"""``sm-settings`` CLI — currently only ``import-from-env``.
+
+One-shot migration: walks every registered module's ``BaseSettings`` and,
+for each field whose legacy ``SM_<PREFIX>_<FIELD>`` env var is set, writes
+a SYSTEM-scoped override into the Settings store.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import sys
+
+from fastapi import FastAPI
+
+from settings.constants import MODULE_PACKAGE
+from settings.env_vars import env_prefix_for
+from settings.hydrate import value_type_for_field
+from settings.store import SettingsStore
+
+
+async def import_from_env_impl(app: FastAPI, store: SettingsStore) -> int:
+    """Write a SYSTEM override for every ``SM_<PREFIX>_<FIELD>`` env var set.
+
+    Returns the count of overrides written. Env vars that don't match a
+    registered field are ignored.
+    """
+    registry = getattr(app.state, MODULE_PACKAGE).module_registry
+    count = 0
+    for package, cls in registry.items():
+        prefix = env_prefix_for(package)
+        for field_name in cls.model_fields:
+            raw = os.environ.get(f"{prefix}{field_name.upper()}")
+            if raw is None:
+                continue
+            vtype = value_type_for_field(cls, field_name)
+            await store.set_override(package, field_name, raw, vtype)
+            count += 1
+    return count
+
+
+def main() -> int:
+    """Console-script entry point for ``sm-settings``.
+
+    Supports a single subcommand: ``import-from-env``.
+    """
+    argv = sys.argv[1:]
+    if not argv or argv[0] in ("-h", "--help"):
+        print("Usage: sm-settings import-from-env")
+        return 0 if argv else 1
+    if argv[0] != "import-from-env":
+        print(f"Unknown command: {argv[0]}", file=sys.stderr)
+        print("Usage: sm-settings import-from-env", file=sys.stderr)
+        return 2
+
+    from simple_module_hosting.app_builder import create_app
+    from simple_module_hosting.settings import Settings
+
+    from settings.service import SettingService
+
+    app = create_app(Settings())
+
+    async def run() -> int:
+        async with (
+            app.router.lifespan_context(app),
+            app.state.sm.db.session_factory() as session,
+        ):
+            store = SettingsStore(SettingService(session))
+            n = await import_from_env_impl(app, store)
+            await session.commit()
+            print(f"Imported {n} override(s) from environment.")
+        return 0
+
+    return asyncio.run(run())
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/modules/settings/settings/constants.py b/modules/settings/settings/constants.py
index 95ddc728..9d95f9f1 100644
--- a/modules/settings/settings/constants.py
+++ b/modules/settings/settings/constants.py
@@ -86,7 +86,7 @@
 PAGE_BROWSE: Final = f"{MODULE_NAME}/Browse"
 PAGE_CREATE: Final = f"{MODULE_NAME}/Create"
 PAGE_EDIT: Final = f"{MODULE_NAME}/Edit"
-PAGE_MODULES: Final = f"{MODULE_NAME}/Modules"
+PAGE_MODULES_EDIT: Final = f"{MODULE_NAME}/ModulesEdit"
 
 # ── Inertia prop keys ────────────────────────────────────────────────
 PROP_SETTINGS: Final = "settings"
diff --git a/modules/settings/settings/contracts/events.py b/modules/settings/settings/contracts/events.py
new file mode 100644
index 00000000..a1cb4d9b
--- /dev/null
+++ b/modules/settings/settings/contracts/events.py
@@ -0,0 +1,20 @@
+"""Domain events published by the Settings module."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from simple_module_core.events import Event
+
+
+@dataclass
+class SettingsReloaded(Event):
+    """Fired after a module's BaseSettings has been reloaded from the DB.
+
+    Subscribers that cached stateful handles built from settings (SMTP client,
+    Celery app config, middleware) can rebuild when ``package`` matches their
+    own.
+    """
+
+    package: str
+    changed: tuple[str, ...]
diff --git a/modules/settings/settings/endpoints/module_api.py b/modules/settings/settings/endpoints/module_api.py
new file mode 100644
index 00000000..4ba88c00
--- /dev/null
+++ b/modules/settings/settings/endpoints/module_api.py
@@ -0,0 +1,102 @@
+"""REST endpoints for the per-module settings admin UI.
+
+PUT drops fields whose value is the mask sentinel so the UI can echo back
+masked secrets without clobbering the real value.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from fastapi import APIRouter, Depends, HTTPException, Request, Response, status
+from pydantic import ValidationError
+
+from settings._module_settings import (
+    SECRET_MASK,
+    collect_module_settings,
+    is_secret_field,
+    serialize,
+)
+from settings.constants import MODULE_PACKAGE
+from settings.contracts.events import SettingsReloaded
+from settings.deps import get_setting_service
+from settings.hydrate import hydrate_settings
+from settings.reload import apply_changes_and_reload
+from settings.service import SettingService
+from settings.store import SettingsStore
+
+router = APIRouter(prefix="/modules", tags=["Settings Modules"])
+
+
+def _strip_mask_sentinels(changes: dict[str, Any]) -> dict[str, Any]:
+    """Drop secret fields whose value is the UI mask sentinel."""
+    return {
+        name: value
+        for name, value in changes.items()
+        if not (isinstance(value, str) and value == SECRET_MASK and is_secret_field(name))
+    }
+
+
+@router.get("")
+async def list_modules(request: Request) -> dict[str, Any]:
+    views = collect_module_settings(request.app)
+    return {"modules": serialize(views)}
+
+
+@router.put("/{package}")
+async def update_module(
+    package: str,
+    changes: dict[str, Any],
+    request: Request,
+    service: SettingService = Depends(get_setting_service),
+) -> dict[str, Any]:
+    registry = getattr(request.app.state, MODULE_PACKAGE).module_registry
+    if registry.get(package) is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Unknown module package")
+
+    cleaned = _strip_mask_sentinels(changes)
+    if not cleaned:
+        return {"ok": True, "changed": []}
+
+    store = SettingsStore(service)
+    bus = request.app.state.sm.event_bus
+    try:
+        await apply_changes_and_reload(request.app, bus, store, package=package, changes=cleaned)
+    except ValidationError as exc:
+        # ``exc.errors()`` still leaves ``ctx.error`` holding the raw Python
+        # exception (not JSON-serializable). Round-trip through pydantic's
+        # own JSON encoder to get clean, serializable errors.
+        clean = json.loads(exc.json(include_url=False))
+        raise HTTPException(status_code=422, detail=clean) from exc
+    except KeyError as exc:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc)) from exc
+
+    return {"ok": True, "changed": sorted(cleaned)}
+
+
+@router.delete("/{package}/{field}", status_code=status.HTTP_204_NO_CONTENT)
+async def clear_module_field(
+    package: str,
+    field: str,
+    request: Request,
+    service: SettingService = Depends(get_setting_service),
+) -> Response:
+    registry = getattr(request.app.state, MODULE_PACKAGE).module_registry
+    cls = registry.get(package)
+    if cls is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Unknown module package")
+    if field not in cls.model_fields:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Unknown field")
+
+    store = SettingsStore(service)
+    await store.clear_override(package, field)
+
+    hydrated = await hydrate_settings(cls, store, package)
+    services = getattr(request.app.state, package)
+    services.settings = hydrated
+
+    bus = request.app.state.sm.event_bus
+    await bus.publish(SettingsReloaded(package=package, changed=(field,)))
+
+    return Response(status_code=status.HTTP_204_NO_CONTENT)
diff --git a/modules/settings/settings/endpoints/views.py b/modules/settings/settings/endpoints/views.py
index 2ed8af7d..21e0d237 100644
--- a/modules/settings/settings/endpoints/views.py
+++ b/modules/settings/settings/endpoints/views.py
@@ -114,4 +114,7 @@ async def modules_view(request: Request, inertia: InertiaDep) -> InertiaResponse
     Auto-discovered from ``app.state.sm.modules``; secrets are masked server-side.
     """
     views = collect_module_settings(request.app)
-    return await inertia.render("Settings/Modules", {PROP_MODULES: serialize(views)})
+    return await inertia.render(
+        "Settings/ModulesEdit",
+        {PROP_MODULES: serialize(views)},
+    )
diff --git a/modules/settings/settings/env_vars.py b/modules/settings/settings/env_vars.py
new file mode 100644
index 00000000..908a3031
--- /dev/null
+++ b/modules/settings/settings/env_vars.py
@@ -0,0 +1,18 @@
+"""Map package names to their historical ``SM_*`` env-var prefix.
+
+Used by ``_module_settings`` to label fields in the admin UI and by the
+``sm-settings import-from-env`` CLI to locate legacy env values. Most
+packages follow ``SM_<PACKAGE_UPPER>_``; the exceptions are listed below.
+"""
+
+from __future__ import annotations
+
+_PACKAGE_ENV_PREFIX: dict[str, str] = {
+    "background_tasks": "SM_BG_TASKS_",
+    "file_storage": "SM_FILE_STORAGE_",
+    "host": "SM_",
+}
+
+
+def env_prefix_for(package: str) -> str:
+    return _PACKAGE_ENV_PREFIX.get(package, f"SM_{package.upper()}_")
diff --git a/modules/settings/settings/hydrate.py b/modules/settings/settings/hydrate.py
new file mode 100644
index 00000000..14fff1b6
--- /dev/null
+++ b/modules/settings/settings/hydrate.py
@@ -0,0 +1,63 @@
+"""Resolve a module's BaseSettings from DB overrides + pydantic defaults.
+
+A field's declared Python type maps to one of the five ``value_type`` labels
+understood by SettingsStore (``string | bool | int | float | json``). The
+hydrator reads overrides, parses each according to its stored ``value_type``,
+and constructs the BaseSettings — pydantic enforces field validators and any
+``@model_validator`` hooks.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import get_origin
+
+from pydantic_settings import BaseSettings
+
+from settings.store import SettingsStore
+
+
+def value_type_for_field(cls: type[BaseSettings], field_name: str) -> str:
+    """Return the ``value_type`` label for a field based on its annotation.
+
+    - ``bool`` → ``"bool"``
+    - ``int`` → ``"int"``
+    - ``float`` → ``"float"``
+    - ``str`` and enums → ``"string"``
+    - ``list``, ``dict``, and other container types → ``"json"``
+    """
+    info = cls.model_fields[field_name]
+    ann = info.annotation
+    origin = get_origin(ann)
+    if origin is not None:
+        return "json"
+    if ann is bool:
+        return "bool"
+    if ann is int:
+        return "int"
+    if ann is float:
+        return "float"
+    return "string"
+
+
+def _parse(raw: str, value_type: str):
+    if value_type == "bool":
+        return raw.lower() in ("1", "true", "yes", "on")
+    if value_type == "int":
+        return int(raw)
+    if value_type == "float":
+        return float(raw)
+    if value_type == "json":
+        return json.loads(raw)
+    return raw
+
+
+async def hydrate_settings[T: BaseSettings](cls: type[T], store: SettingsStore, package: str) -> T:
+    """Construct ``cls`` with DB overrides merged over pydantic defaults."""
+    raw_overrides = await store.get_overrides(package)
+    parsed: dict[str, object] = {}
+    for field_name, (raw, vtype) in raw_overrides.items():
+        if field_name not in cls.model_fields:
+            continue
+        parsed[field_name] = _parse(raw, vtype)
+    return cls(**parsed)
diff --git a/modules/settings/settings/locales/en.json b/modules/settings/settings/locales/en.json
index c68688e9..37f018de 100644
--- a/modules/settings/settings/locales/en.json
+++ b/modules/settings/settings/locales/en.json
@@ -57,6 +57,9 @@
     "no_fields": "No fields declared.",
     "secret_badge": "secret",
     "browse_link": "View module settings",
+    "search_placeholder": "Search modules or fields…",
+    "field_count_suffix": "fields",
+    "browse_free_form_link": "View free-form settings",
     "table": {
       "field": "Field",
       "env_var": "Env var",
diff --git a/modules/settings/settings/module.py b/modules/settings/settings/module.py
index dbff6fe6..dd965ff9 100644
--- a/modules/settings/settings/module.py
+++ b/modules/settings/settings/module.py
@@ -33,15 +33,27 @@ class SettingsModule(ModuleBase):
     )
 
     def register_settings(self, app: FastAPI) -> None:
+        from settings.contracts.registry import SettingsRegistry
+        from settings.module_registry import ModuleSettingsRegistry
         from settings.services import SettingsServices
         from settings.settings import SettingsSettings
 
-        setattr(app.state, MODULE_PACKAGE, SettingsServices(settings=SettingsSettings()))
+        services = SettingsServices(
+            settings=SettingsSettings(),
+            registry=SettingsRegistry(),
+            module_registry=ModuleSettingsRegistry(),
+        )
+        setattr(app.state, MODULE_PACKAGE, services)
+
+        # Self-register so the UI lists our own settings alongside other modules.
+        services.module_registry.register("settings", SettingsSettings)
 
     def register_routes(self, api_router: APIRouter, view_router: APIRouter) -> None:
         from settings.endpoints.api import router as api
+        from settings.endpoints.module_api import router as module_api
         from settings.endpoints.views import router as views
 
+        api_router.include_router(module_api)
         api_router.include_router(api)
         view_router.include_router(views)
 
diff --git a/modules/settings/settings/module_registry.py b/modules/settings/settings/module_registry.py
new file mode 100644
index 00000000..bd28c7e8
--- /dev/null
+++ b/modules/settings/settings/module_registry.py
@@ -0,0 +1,33 @@
+"""Registry of per-module pydantic BaseSettings classes.
+
+Populated during each module's ``register_settings`` via
+``register_module_settings``. The hosting lifespan reads this at startup
+to hydrate every module's effective settings from the DB.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from pydantic_settings import BaseSettings
+
+
+@dataclass(slots=True)
+class ModuleSettingsRegistry:
+    """In-memory map of ``package`` → ``BaseSettings`` subclass."""
+
+    _classes: dict[str, type[BaseSettings]] = field(default_factory=dict)
+
+    def register(self, package: str, cls: type[BaseSettings]) -> None:
+        if package in self._classes:
+            raise ValueError(f"{package!r} already registered")
+        self._classes[package] = cls
+
+    def get(self, package: str) -> type[BaseSettings] | None:
+        return self._classes.get(package)
+
+    def all_packages(self) -> list[str]:
+        return sorted(self._classes)
+
+    def items(self) -> list[tuple[str, type[BaseSettings]]]:
+        return sorted(self._classes.items())
diff --git a/modules/settings/settings/pages/Modules.tsx b/modules/settings/settings/pages/Modules.tsx
deleted file mode 100644
index 4aca5877..00000000
--- a/modules/settings/settings/pages/Modules.tsx
+++ /dev/null
@@ -1,115 +0,0 @@
-import { keys, useT } from '@simple-module/i18n';
-import { AuthenticatedLayout } from '@simple-module/ui/layouts/AuthenticatedLayout';
-import type React from 'react';
-import { ROUTES } from './routes';
-
-type FieldView = {
-  name: string;
-  env_var: string;
-  value: unknown;
-  default: unknown;
-  description: string;
-  is_secret: boolean;
-};
-
-type ModuleView = {
-  module_name: string;
-  package: string;
-  env_prefix: string;
-  class_name: string;
-  fields: FieldView[];
-};
-
-type Props = { modules: ModuleView[] };
-
-function formatValue(v: unknown): string {
-  if (v === null || v === undefined) return '—';
-  if (typeof v === 'string') return v === '' ? '""' : v;
-  if (typeof v === 'boolean' || typeof v === 'number') return String(v);
-  return JSON.stringify(v);
-}
-
-function Modules({ modules }: Props) {
-  const { t } = useT();
-  return (
-    <div className="p-6 space-y-6">
-      <div className="flex items-center justify-between">
-        <div>
-          <h1 className="text-2xl font-semibold">{t(keys.settings.modules.title)}</h1>
-          <p className="text-sm text-muted-foreground mt-1">
-            {t(keys.settings.modules.description)}
-          </p>
-        </div>
-        <a href={ROUTES.browse} className="text-sm text-primary hover:underline">
-          {t(keys.settings.modules.back_link)}
-        </a>
-      </div>
-
-      {modules.length === 0 ? (
-        <div className="py-12 text-center">
-          <h2 className="text-lg font-medium">{t(keys.settings.modules.empty_title)}</h2>
-        </div>
-      ) : (
-        <div className="space-y-6">
-          {modules.map((m) => (
-            <section key={m.package} className="rounded border">
-              <header className="flex items-baseline justify-between border-b bg-muted/40 px-4 py-3">
-                <div>
-                  <h2 className="text-lg font-semibold">{m.module_name}</h2>
-                  <p className="text-xs text-muted-foreground">
-                    {m.class_name}
-                    {m.env_prefix ? ` · ${m.env_prefix}*` : ''}
-                  </p>
-                </div>
-                <span className="text-xs font-mono text-muted-foreground">{m.package}</span>
-              </header>
-
-              {m.fields.length === 0 ? (
-                <p className="px-4 py-6 text-sm text-muted-foreground">
-                  {t(keys.settings.modules.no_fields)}
-                </p>
-              ) : (
-                <table className="w-full text-left border-collapse text-sm">
-                  <thead>
-                    <tr className="border-b">
-                      <th className="py-2 px-4">{t(keys.settings.modules.table.field)}</th>
-                      <th className="py-2 px-4">{t(keys.settings.modules.table.env_var)}</th>
-                      <th className="py-2 px-4">{t(keys.settings.modules.table.value)}</th>
-                      <th className="py-2 px-4">{t(keys.settings.modules.table.default)}</th>
-                      <th className="py-2 px-4">{t(keys.settings.modules.table.description)}</th>
-                    </tr>
-                  </thead>
-                  <tbody>
-                    {m.fields.map((f) => (
-                      <tr key={f.name} className="border-b last:border-b-0">
-                        <td className="py-2 px-4 font-mono text-xs">{f.name}</td>
-                        <td className="py-2 px-4 font-mono text-xs text-muted-foreground">
-                          {f.env_var}
-                        </td>
-                        <td className="py-2 px-4 font-mono text-xs">
-                          {formatValue(f.value)}
-                          {f.is_secret && (
-                            <span className="ml-2 rounded bg-amber-100 px-1.5 py-0.5 text-[10px] uppercase text-amber-900">
-                              {t(keys.settings.modules.secret_badge)}
-                            </span>
-                          )}
-                        </td>
-                        <td className="py-2 px-4 font-mono text-xs text-muted-foreground">
-                          {formatValue(f.default)}
-                        </td>
-                        <td className="py-2 px-4 text-muted-foreground">{f.description || '—'}</td>
-                      </tr>
-                    ))}
-                  </tbody>
-                </table>
-              )}
-            </section>
-          ))}
-        </div>
-      )}
-    </div>
-  );
-}
-
-Modules.layout = (page: React.ReactNode) => <AuthenticatedLayout>{page}</AuthenticatedLayout>;
-export default Modules;
diff --git a/modules/settings/settings/pages/ModulesEdit.tsx b/modules/settings/settings/pages/ModulesEdit.tsx
new file mode 100644
index 00000000..589ac9ed
--- /dev/null
+++ b/modules/settings/settings/pages/ModulesEdit.tsx
@@ -0,0 +1,74 @@
+import { keys, useT } from '@simple-module/i18n';
+import { AuthenticatedLayout } from '@simple-module/ui/layouts/AuthenticatedLayout';
+import type React from 'react';
+import { useMemo, useState } from 'react';
+import { ModuleForm, type ModuleView } from './components/ModuleForm';
+import { ROUTES } from './routes';
+
+type Props = { modules: ModuleView[] };
+
+function ModulesEdit({ modules }: Props) {
+  const { t } = useT();
+  const [selected, setSelected] = useState(modules[0]?.package);
+  const [q, setQ] = useState('');
+
+  const filtered = useMemo(() => {
+    if (!q) return modules;
+    const query = q.toLowerCase();
+    return modules.filter(
+      (m) =>
+        m.module_name.toLowerCase().includes(query) ||
+        m.package.toLowerCase().includes(query) ||
+        m.fields.some((f) => f.name.toLowerCase().includes(query)),
+    );
+  }, [modules, q]);
+
+  const current = modules.find((m) => m.package === selected);
+
+  return (
+    <div className="flex h-[calc(100vh-64px)]">
+      <aside className="w-64 border-r bg-muted/40 p-3 overflow-y-auto">
+        <input
+          type="text"
+          placeholder={t(keys.settings.modules.search_placeholder)}
+          value={q}
+          onChange={(e) => setQ(e.target.value)}
+          className="mb-3 w-full rounded border px-2 py-1 text-sm"
+        />
+        <nav className="space-y-1">
+          {filtered.map((m) => (
+            <button
+              key={m.package}
+              type="button"
+              onClick={() => setSelected(m.package)}
+              className={`block w-full rounded px-3 py-2 text-left text-sm ${
+                m.package === selected ? 'bg-primary text-primary-foreground' : 'hover:bg-muted'
+              }`}
+            >
+              <div className="font-medium">{m.module_name}</div>
+              <div className="text-xs opacity-70">
+                {m.fields.length} {t(keys.settings.modules.field_count_suffix)}
+              </div>
+            </button>
+          ))}
+        </nav>
+        <div className="mt-4 border-t pt-3 text-xs">
+          <a href={ROUTES.browse} className="text-primary hover:underline">
+            {t(keys.settings.modules.browse_free_form_link)}
+          </a>
+        </div>
+      </aside>
+
+      <main className="flex-1 overflow-y-auto p-6">
+        {current ? (
+          <ModuleForm module={current} />
+        ) : (
+          <p className="text-muted-foreground">{t(keys.settings.modules.empty_title)}</p>
+        )}
+      </main>
+    </div>
+  );
+}
+
+ModulesEdit.layout = (page: React.ReactNode) => <AuthenticatedLayout>{page}</AuthenticatedLayout>;
+export default ModulesEdit;
diff --git a/modules/settings/settings/pages/components/FieldInput.tsx b/modules/settings/settings/pages/components/FieldInput.tsx
new file mode 100644
index 00000000..0228f8b3
--- /dev/null
+++ b/modules/settings/settings/pages/components/FieldInput.tsx
@@ -0,0 +1,96 @@
+import { useState } from 'react';
+
+export type FieldType = 'bool' | 'int' | 'float' | 'string' | 'json';
+
+export type FieldMeta = {
+  name: string;
+  type: FieldType;
+  value: unknown;
+  default: unknown;
+  description: string;
+  is_secret: boolean;
+  requires_restart: boolean;
+  group: string | null;
+  env_var: string;
+};
+
+type Props = {
+  field: FieldMeta;
+  onChange: (name: string, value: unknown) => void;
+  value: unknown;
+  id?: string;
+};
+
+export function FieldInput({ field, onChange, value, id }: Props) {
+  const [revealed, setRevealed] = useState(false);
+
+  if (field.is_secret && !revealed) {
+    return (
+      <div className="flex items-center gap-2">
+        <input
+          id={id}
+          type="password"
+          value="••••••••"
+          readOnly
+          className="w-full rounded border px-2 py-1 font-mono text-sm"
+        />
+        <button
+          type="button"
+          className="text-sm text-primary hover:underline"
+          onClick={() => {
+            setRevealed(true);
+            onChange(field.name, ''); // start blank
+          }}
+        >
+          Set new value
+        </button>
+      </div>
+    );
+  }
+
+  switch (field.type) {
+    case 'bool':
+      return (
+        <input
+          id={id}
+          type="checkbox"
+          checked={!!value}
+          onChange={(e) => onChange(field.name, e.target.checked)}
+        />
+      );
+    case 'int':
+    case 'float':
+      return (
+        <input
+          id={id}
+          type="number"
+          step={field.type === 'int' ? '1' : 'any'}
+          value={String(value ?? '')}
+          onChange={(e) =>
+            onChange(field.name, e.target.value === '' ? null : Number(e.target.value))
+          }
+          className="w-full rounded border px-2 py-1 font-mono text-sm"
+        />
+      );
+    case 'json':
+      return (
+        <textarea
+          id={id}
+          rows={3}
+          value={typeof value === 'string' ? value : JSON.stringify(value, null, 2)}
+          onChange={(e) => onChange(field.name, e.target.value)}
+          className="w-full rounded border px-2 py-1 font-mono text-xs"
+        />
+      );
+    default:
+      return (
+        <input
+          id={id}
+          type="text"
+          value={String(value ?? '')}
+          onChange={(e) => onChange(field.name, e.target.value)}
+          className="w-full rounded border px-2 py-1 font-mono text-sm"
+        />
+      );
+  }
+}
diff --git a/modules/settings/settings/pages/components/ModuleForm.tsx b/modules/settings/settings/pages/components/ModuleForm.tsx
new file mode 100644
index 00000000..ecdd8fb1
--- /dev/null
+++ b/modules/settings/settings/pages/components/ModuleForm.tsx
@@ -0,0 +1,157 @@
+import { router } from '@inertiajs/react';
+import { useEffect, useMemo, useState } from 'react';
+import { FieldInput, type FieldMeta } from './FieldInput';
+
+export type ModuleView = {
+  module_name: string;
+  package: string;
+  env_prefix: string;
+  class_name: string;
+  fields: FieldMeta[];
+};
+
+type Props = { module: ModuleView };
+
+function notEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return false;
+  if (typeof a === 'object' || typeof b === 'object') {
+    return JSON.stringify(a) !== JSON.stringify(b);
+  }
+  return true;
+}
+
+export function ModuleForm({ module: m }: Props) {
+  const initial = useMemo(() => {
+    const o: Record<string, unknown> = {};
+    for (const f of m.fields) o[f.name] = f.value;
+    return o;
+  }, [m.fields]);
+
+  const [values, setValues] = useState<Record<string, unknown>>(initial);
+  const [errors, setErrors] = useState<Record<string, string>>({});
+  const [busy, setBusy] = useState(false);
+
+  // Reset the edit buffer whenever the underlying module changes (package
+  // switch, or server-reloaded props after a save/reset).
+  useEffect(() => {
+    setValues(initial);
+    setErrors({});
+  }, [initial]);
+
+  const modifiedFields = useMemo(() => {
+    const s = new Set<string>();
+    for (const name of Object.keys(values)) {
+      if (notEqual(values[name], initial[name])) s.add(name);
+    }
+    return s;
+  }, [values, initial]);
+
+  const defaultByName = useMemo(() => {
+    const o: Record<string, unknown> = {};
+    for (const f of m.fields) o[f.name] = f.default;
+    return o;
+  }, [m.fields]);
+
+  const dirty = modifiedFields.size > 0;
+
+  const grouped = useMemo(() => {
+    const g: Record<string, FieldMeta[]> = {};
+    for (const f of m.fields) {
+      const key = f.group ?? 'General';
+      if (!g[key]) g[key] = [];
+      g[key].push(f);
+    }
+    return g;
+  }, [m.fields]);
+
+  async function onSave() {
+    setBusy(true);
+    setErrors({});
+    const changed: Record<string, unknown> = {};
+    for (const name of modifiedFields) changed[name] = values[name];
+    const resp = await fetch(`/api/settings/modules/${m.package}`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(changed),
+    });
+    if (resp.status === 422) {
+      const body = await resp.json();
+      const fieldErrs: Record<string, string> = {};
+      for (const d of body.detail ?? []) {
+        if (d.loc && d.loc.length) fieldErrs[d.loc[d.loc.length - 1]] = d.msg;
+      }
+      setErrors(fieldErrs);
+    } else if (resp.ok) {
+      router.reload({ only: ['modules'] });
+    }
+    setBusy(false);
+  }
+
+  async function onReset(name: string) {
+    await fetch(`/api/settings/modules/${m.package}/${name}`, { method: 'DELETE' });
+    router.reload({ only: ['modules'] });
+  }
+
+  return (
+    <div className="space-y-6">
+      <header className="flex items-center justify-between border-b pb-3">
+        <div>
+          <h2 className="text-xl font-semibold">{m.module_name}</h2>
+          <p className="text-xs font-mono text-muted-foreground">{m.package}</p>
+        </div>
+        <button
+          type="button"
+          disabled={!dirty || busy}
+          onClick={onSave}
+          className="rounded bg-primary px-4 py-2 text-sm text-primary-foreground disabled:opacity-50"
+        >
+          {busy ? 'Saving…' : 'Save'}
+        </button>
+      </header>
+
+      {Object.entries(grouped).map(([group, fields]) => (
+        <section key={group} className="space-y-3">
+          <h3 className="text-sm font-semibold text-muted-foreground">{group}</h3>
+          {fields.map((f) => {
+            const isModified = notEqual(values[f.name], defaultByName[f.name]);
+            return (
+              <div key={f.name} className="grid grid-cols-[1fr_2fr] gap-4 items-start">
+                <div>
+                  <label htmlFor={`field-${m.package}-${f.name}`} className="font-mono text-xs">
+                    {f.name}
+                  </label>
+                  {f.description && (
+                    <p className="mt-1 text-xs text-muted-foreground">{f.description}</p>
+                  )}
+                  {f.requires_restart && isModified && (
+                    <span className="mt-1 inline-block rounded bg-amber-100 px-1.5 py-0.5 text-[10px] uppercase text-amber-900">
+                      Requires restart
+                    </span>
+                  )}
+                </div>
+                <div>
+                  <FieldInput
+                    id={`field-${m.package}-${f.name}`}
+                    field={f}
+                    value={values[f.name]}
+                    onChange={(name, v) => setValues((prev) => ({ ...prev, [name]: v }))}
+                  />
+                  {isModified && (
+                    <button
+                      type="button"
+                      onClick={() => onReset(f.name)}
+                      className="mt-1 text-xs text-primary hover:underline"
+                    >
+                      Reset to default
+                    </button>
+                  )}
+                  {errors[f.name] && <p className="mt-1 text-xs text-red-600">{errors[f.name]}</p>}
+                </div>
+              </div>
+            );
+          })}
+        </section>
+      ))}
+    </div>
+  );
+}
diff --git a/modules/settings/settings/registration.py b/modules/settings/settings/registration.py
new file mode 100644
index 00000000..2ab3196f
--- /dev/null
+++ b/modules/settings/settings/registration.py
@@ -0,0 +1,34 @@
+"""Helper modules call from ``register_settings`` to install their BaseSettings.
+
+Two things happen:
+1. A fresh ``BaseSettings`` (pydantic defaults only) is constructed.
+2. The class is recorded in ``app.state.settings.module_registry`` so the
+   hosting lifespan can hydrate it from the DB before module ``on_startup``
+   hooks run.
+
+The module's services dataclass is built from the default settings object and
+attached at ``app.state.<package>``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from fastapi import FastAPI
+from pydantic_settings import BaseSettings
+
+from settings.constants import MODULE_PACKAGE
+
+
+def register_module_settings(
+    app: FastAPI,
+    package: str,
+    settings_cls: type[BaseSettings],
+    services_factory: Callable[[BaseSettings], Any],
+) -> None:
+    """Register a module's BaseSettings class and mount its services on app.state."""
+    registry = getattr(app.state, MODULE_PACKAGE).module_registry
+    registry.register(package, settings_cls)
+    defaults = settings_cls()
+    setattr(app.state, package, services_factory(defaults))
diff --git a/modules/settings/settings/reload.py b/modules/settings/settings/reload.py
new file mode 100644
index 00000000..e7be49fe
--- /dev/null
+++ b/modules/settings/settings/reload.py
@@ -0,0 +1,58 @@
+"""Apply field changes to a module's settings, validate, persist, hot-swap."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from fastapi import FastAPI
+from pydantic_settings import BaseSettings
+from simple_module_core.events import EventBus
+
+from settings.constants import MODULE_PACKAGE
+from settings.contracts.events import SettingsReloaded
+from settings.hydrate import value_type_for_field
+from settings.store import SettingsStore
+
+
+def _encode(value: Any, value_type: str) -> str:
+    if value_type == "json":
+        return json.dumps(value)
+    return str(value)
+
+
+async def apply_changes_and_reload(
+    app: FastAPI,
+    bus: EventBus,
+    store: SettingsStore,
+    *,
+    package: str,
+    changes: dict[str, Any],
+) -> BaseSettings:
+    """Validate, persist, hot-swap, and publish ``SettingsReloaded``."""
+    registry = getattr(app.state, MODULE_PACKAGE).module_registry
+    cls = registry.get(package)
+    if cls is None:
+        raise KeyError(f"Unknown settings package: {package!r}")
+
+    unknown = set(changes) - set(cls.model_fields)
+    if unknown:
+        raise KeyError(f"Unknown field(s) for {package!r}: {sorted(unknown)}")
+
+    services = getattr(app.state, package)
+    current = services.settings
+    diff = {k: v for k, v in changes.items() if getattr(current, k) != v}
+    if not diff:
+        return current
+
+    merged = current.model_dump()
+    merged.update(diff)
+    validated = cls(**merged)
+
+    for field_name, raw_value in diff.items():
+        vtype = value_type_for_field(cls, field_name)
+        await store.set_override(package, field_name, _encode(raw_value, vtype), vtype)
+
+    services.settings = validated
+    await bus.publish(SettingsReloaded(package=package, changed=tuple(sorted(diff))))
+    return validated
diff --git a/modules/settings/settings/services.py b/modules/settings/settings/services.py
index bf7e60e8..ea079afa 100644
--- a/modules/settings/settings/services.py
+++ b/modules/settings/settings/services.py
@@ -13,6 +13,7 @@
 from dataclasses import dataclass, field
 
 from settings.contracts.registry import SettingsRegistry
+from settings.module_registry import ModuleSettingsRegistry
 from settings.settings import SettingsSettings
 
 
@@ -24,7 +25,12 @@ class SettingsServices:
     their setting keys here (typically from their own ``on_startup`` hook)
     so admins can discover every knob and the accessor can fall back to
     declared defaults.
+
+    ``module_registry`` tracks per-module ``BaseSettings`` classes registered
+    via ``register_module_settings``; the hosting lifespan uses it to hydrate
+    each module's effective settings from the DB before ``on_startup`` runs.
     """
 
     settings: SettingsSettings
     registry: SettingsRegistry = field(default_factory=SettingsRegistry)
+    module_registry: ModuleSettingsRegistry = field(default_factory=ModuleSettingsRegistry)
diff --git a/modules/settings/settings/settings.py b/modules/settings/settings/settings.py
index 65b82a0f..99a27ed2 100644
--- a/modules/settings/settings/settings.py
+++ b/modules/settings/settings/settings.py
@@ -1,4 +1,4 @@
-"""Settings module configuration loaded from SM_SETTINGS_* environment variables."""
+"""Settings module's own configuration (DB-backed)."""
 
 from __future__ import annotations
 
@@ -8,4 +8,4 @@
 class SettingsSettings(BaseSettings):
     """Configuration for the Settings module."""
 
-    model_config = SettingsConfigDict(env_prefix="SM_SETTINGS_", env_file=".env", extra="ignore")
+    model_config = SettingsConfigDict(extra="ignore")
diff --git a/modules/settings/settings/store.py b/modules/settings/settings/store.py
new file mode 100644
index 00000000..a7d9f7d3
--- /dev/null
+++ b/modules/settings/settings/store.py
@@ -0,0 +1,61 @@
+"""DB-backed key/value store for module settings (SYSTEM scope).
+
+Wraps the existing SettingService. Keys are namespaced ``<package>.<field>``
+to avoid collision with free-form user-defined setting keys.
+"""
+
+from __future__ import annotations
+
+from settings.constants import SYSTEM_SCOPE_ID
+from settings.contracts.schemas import SettingScope, SettingUpsert, SettingValueType
+from settings.service import SettingService
+
+
+def _key(package: str, field: str) -> str:
+    return f"{package}.{field}"
+
+
+class SettingsStore:
+    """SYSTEM-scoped key/value store keyed by ``(package, field)``."""
+
+    def __init__(self, service: SettingService) -> None:
+        self._service = service
+
+    async def get_overrides(self, package: str) -> dict[str, tuple[str, str]]:
+        """Return ``{field_name: (raw_value, value_type)}`` for a package."""
+        prefix = f"{package}."
+        items = await self._service.list_by_scope(SettingScope.SYSTEM, SYSTEM_SCOPE_ID)
+        out: dict[str, tuple[str, str]] = {}
+        for item in items:
+            if not item.key.startswith(prefix):
+                continue
+            field_name = item.key[len(prefix) :]
+            if "." in field_name:
+                continue
+            out[field_name] = (item.value, item.value_type)
+        return out
+
+    async def set_override(self, package: str, field: str, value: str, value_type: str) -> None:
+        await self._service.upsert_scoped(
+            SettingScope.SYSTEM,
+            SYSTEM_SCOPE_ID,
+            _key(package, field),
+            SettingUpsert(value=value, value_type=SettingValueType(value_type)),
+        )
+
+    async def clear_override(self, package: str, field: str) -> None:
+        await self._service.delete_scoped(
+            SettingScope.SYSTEM, SYSTEM_SCOPE_ID, _key(package, field)
+        )
+
+    async def list_packages_with_overrides(self) -> list[str]:
+        items = await self._service.list_by_scope(SettingScope.SYSTEM, SYSTEM_SCOPE_ID)
+        pkgs: set[str] = set()
+        for item in items:
+            if "." not in item.key:
+                continue
+            pkg, rest = item.key.split(".", 1)
+            if "." in rest:
+                continue
+            pkgs.add(pkg)
+        return sorted(pkgs)
diff --git a/modules/settings/tests/test_cli_import.py b/modules/settings/tests/test_cli_import.py
new file mode 100644
index 00000000..bf7e792e
--- /dev/null
+++ b/modules/settings/tests/test_cli_import.py
@@ -0,0 +1,44 @@
+"""Tests for the ``sm-settings import-from-env`` CLI entry point.
+
+Exercises ``import_from_env_impl`` directly so we avoid spawning a real
+process but still cover the env → DB override path the CLI wraps.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+
+@pytest.mark.asyncio
+async def test_import_from_env_writes_overrides(db_session, monkeypatch, app) -> None:
+    monkeypatch.setenv("SM_USERS_ALLOW_SIGNUP", "true")
+    monkeypatch.setenv("SM_USERS_SMTP_PORT", "2525")
+    monkeypatch.setenv("SM_BG_TASKS_RETENTION_DAYS", "30")
+
+    from settings.cli import import_from_env_impl
+    from settings.service import SettingService
+    from settings.store import SettingsStore
+
+    store = SettingsStore(SettingService(db_session))
+    n = await import_from_env_impl(app, store)
+
+    users = await store.get_overrides("users")
+    bg = await store.get_overrides("background_tasks")
+    assert users["allow_signup"] == ("true", "bool")
+    assert users["smtp_port"] == ("2525", "int")
+    assert bg["retention_days"] == ("30", "int")
+    assert n == 3
+
+
+@pytest.mark.asyncio
+async def test_import_ignores_unknown_env(db_session, monkeypatch, app) -> None:
+    monkeypatch.setenv("SM_USERS_DOES_NOT_EXIST", "value")
+
+    from settings.cli import import_from_env_impl
+    from settings.service import SettingService
+    from settings.store import SettingsStore
+
+    store = SettingsStore(SettingService(db_session))
+    n = await import_from_env_impl(app, store)
+    assert n == 0
+    assert await store.get_overrides("users") == {}
diff --git a/modules/settings/tests/test_hydrate.py b/modules/settings/tests/test_hydrate.py
new file mode 100644
index 00000000..6630cb1b
--- /dev/null
+++ b/modules/settings/tests/test_hydrate.py
@@ -0,0 +1,65 @@
+"""Tests for hydrate_settings — resolve DB overrides into a BaseSettings instance."""
+
+from __future__ import annotations
+
+import pytest
+from pydantic import ValidationError
+from pydantic_settings import BaseSettings
+from settings.hydrate import hydrate_settings, value_type_for_field
+from settings.service import SettingService
+from settings.store import SettingsStore
+
+
+class _Cfg(BaseSettings):
+    allow: bool = False
+    port: int = 25
+    host: str = "localhost"
+    tags: list[str] = ["a"]
+    rate: float = 1.5
+
+
+@pytest.mark.asyncio
+async def test_hydrate_returns_defaults_when_no_overrides(db_session) -> None:
+    store = SettingsStore(SettingService(db_session))
+    cfg = await hydrate_settings(_Cfg, store, package="demo")
+    assert cfg == _Cfg()
+
+
+@pytest.mark.asyncio
+async def test_hydrate_applies_scalar_overrides(db_session) -> None:
+    store = SettingsStore(SettingService(db_session))
+    await store.set_override("demo", "allow", "true", "bool")
+    await store.set_override("demo", "port", "587", "int")
+    await store.set_override("demo", "host", "mail.example.com", "string")
+    await store.set_override("demo", "rate", "2.5", "float")
+
+    cfg = await hydrate_settings(_Cfg, store, package="demo")
+    assert cfg.allow is True
+    assert cfg.port == 587
+    assert cfg.host == "mail.example.com"
+    assert cfg.rate == 2.5
+
+
+@pytest.mark.asyncio
+async def test_hydrate_applies_json_list_override(db_session) -> None:
+    store = SettingsStore(SettingService(db_session))
+    await store.set_override("demo", "tags", '["x","y","z"]', "json")
+    cfg = await hydrate_settings(_Cfg, store, package="demo")
+    assert cfg.tags == ["x", "y", "z"]
+
+
+@pytest.mark.asyncio
+async def test_hydrate_raises_on_pydantic_validation_error(db_session) -> None:
+    store = SettingsStore(SettingService(db_session))
+    # Stored as json (valid JSON), but a list can't coerce to int → pydantic rejects.
+    await store.set_override("demo", "port", "[1,2,3]", "json")
+    with pytest.raises(ValidationError):
+        await hydrate_settings(_Cfg, store, package="demo")
+
+
+def test_value_type_for_bool_int_float_str_list() -> None:
+    assert value_type_for_field(_Cfg, "allow") == "bool"
+    assert value_type_for_field(_Cfg, "port") == "int"
+    assert value_type_for_field(_Cfg, "rate") == "float"
+    assert value_type_for_field(_Cfg, "host") == "string"
+    assert value_type_for_field(_Cfg, "tags") == "json"
diff --git a/modules/settings/tests/test_module_api.py b/modules/settings/tests/test_module_api.py
new file mode 100644
index 00000000..436e9adf
--- /dev/null
+++ b/modules/settings/tests/test_module_api.py
@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import pytest
+
+
+@pytest.mark.asyncio
+async def test_get_modules_returns_registered_packages(authenticated_client):
+    resp = await authenticated_client.get("/api/settings/modules")
+    assert resp.status_code == 200
+    payload = resp.json()
+    packages = {m["package"] for m in payload["modules"]}
+    assert {"settings", "host"} <= packages
+
+
+@pytest.mark.asyncio
+async def test_put_module_setting_persists_and_hot_reloads(authenticated_client, app):
+    resp = await authenticated_client.put(
+        "/api/settings/modules/host",
+        json={"multi_tenant": True},
+    )
+    assert resp.status_code == 200, resp.text
+    assert app.state.host.settings.multi_tenant is True
+
+
+@pytest.mark.asyncio
+async def test_put_validation_error_surfaces_422(authenticated_client, app):
+    resp = await authenticated_client.put(
+        "/api/settings/modules/host",
+        json={"i18n_default_locale": "de"},
+    )
+    assert resp.status_code == 422
+    assert "i18n_default_locale" in resp.text
+
+
+@pytest.mark.asyncio
+async def test_delete_field_resets_to_default(authenticated_client, app):
+    await authenticated_client.put("/api/settings/modules/host", json={"multi_tenant": True})
+    assert app.state.host.settings.multi_tenant is True
+    resp = await authenticated_client.delete("/api/settings/modules/host/multi_tenant")
+    assert resp.status_code == 204
+    assert app.state.host.settings.multi_tenant is False
+
+
+@pytest.mark.asyncio
+async def test_put_secret_mask_sentinel_is_noop(authenticated_client, app):
+    await authenticated_client.put(
+        "/api/settings/modules/users",
+        json={"reset_password_token_secret": "real-secret-value-48-chars-long-xxxxxxxxxx"},
+    )
+    original = app.state.users.settings.reset_password_token_secret
+    resp = await authenticated_client.put(
+        "/api/settings/modules/users",
+        json={"reset_password_token_secret": "••••••••"},
+    )
+    assert resp.status_code == 200
+    assert app.state.users.settings.reset_password_token_secret == original
diff --git a/modules/settings/tests/test_module_registry.py b/modules/settings/tests/test_module_registry.py
new file mode 100644
index 00000000..580dfc9d
--- /dev/null
+++ b/modules/settings/tests/test_module_registry.py
@@ -0,0 +1,39 @@
+"""Tests for ModuleSettingsRegistry — tracks {package: BaseSettings_cls}."""
+
+from __future__ import annotations
+
+import pytest
+from pydantic_settings import BaseSettings
+from settings.module_registry import ModuleSettingsRegistry
+
+
+class _Foo(BaseSettings):
+    x: int = 7
+
+
+class _Bar(BaseSettings):
+    y: str = "z"
+
+
+def test_register_and_get() -> None:
+    r = ModuleSettingsRegistry()
+    r.register("foo", _Foo)
+    assert r.get("foo") is _Foo
+
+
+def test_register_duplicate_raises() -> None:
+    r = ModuleSettingsRegistry()
+    r.register("foo", _Foo)
+    with pytest.raises(ValueError, match="already registered"):
+        r.register("foo", _Foo)
+
+
+def test_all_packages_sorted() -> None:
+    r = ModuleSettingsRegistry()
+    r.register("bar", _Bar)
+    r.register("foo", _Foo)
+    assert r.all_packages() == ["bar", "foo"]
+
+
+def test_get_missing_returns_none() -> None:
+    assert ModuleSettingsRegistry().get("nope") is None
diff --git a/modules/settings/tests/test_module_settings.py b/modules/settings/tests/test_module_settings.py
new file mode 100644
index 00000000..ac3ae61c
--- /dev/null
+++ b/modules/settings/tests/test_module_settings.py
@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from fastapi import FastAPI
+from pydantic import Field
+from pydantic_settings import BaseSettings
+from settings._module_settings import collect_module_settings
+from settings.services import SettingsServices
+from settings.settings import SettingsSettings
+from simple_module_core.module import ModuleMeta
+from simple_module_core.services import Services
+
+
+class _DemoCfg(BaseSettings):
+    allow: bool = False
+    port: int = Field(default=25, json_schema_extra={"requires_restart": True, "group": "SMTP"})
+    host: str = Field(default="localhost", json_schema_extra={"group": "SMTP"})
+    secret: str = ""
+
+
+class _DemoModule:
+    meta = ModuleMeta(name="Demo")
+
+
+# Force ``type(mod).__module__`` to resolve to "demo" so _package_of returns
+# "demo" (matching the app.state.demo attribute the collector reads).
+_DemoModule.__module__ = "demo"
+
+
+@dataclass
+class _DemoServices:
+    settings: _DemoCfg
+
+
+def test_collect_exposes_type_requires_restart_group():
+    app = FastAPI()
+    app.state.settings = SettingsServices(settings=SettingsSettings())
+    app.state.settings.module_registry.register("demo", _DemoCfg)
+
+    app.state.demo = _DemoServices(settings=_DemoCfg())
+    app.state.sm = Services(
+        settings=None,  # type: ignore[arg-type]
+        db=None,  # type: ignore[arg-type]
+        event_bus=None,  # type: ignore[arg-type]
+        menu_registry=None,  # type: ignore[arg-type]
+        permissions=None,  # type: ignore[arg-type]
+        feature_flags=None,  # type: ignore[arg-type]
+        health_registry=None,  # type: ignore[arg-type]
+        i18n_registry=None,  # type: ignore[arg-type]
+        inertia_config=None,  # type: ignore[arg-type]
+        modules=(_DemoModule(),),  # type: ignore[arg-type]
+    )
+
+    views = collect_module_settings(app)
+    demo = next(v for v in views if v.package == "demo")
+    by_name = {f.name: f for f in demo.fields}
+    assert by_name["allow"].type == "bool"
+    assert by_name["port"].type == "int"
+    assert by_name["port"].requires_restart is True
+    assert by_name["port"].group == "SMTP"
+    assert by_name["host"].group == "SMTP"
+    assert by_name["allow"].group is None
+    assert by_name["secret"].is_secret is True
diff --git a/modules/settings/tests/test_registration.py b/modules/settings/tests/test_registration.py
new file mode 100644
index 00000000..0a68238d
--- /dev/null
+++ b/modules/settings/tests/test_registration.py
@@ -0,0 +1,51 @@
+"""Tests for register_module_settings — helper modules call during boot."""
+
+from __future__ import annotations
+
+import pytest
+from fastapi import FastAPI
+from pydantic_settings import BaseSettings
+from settings.module_registry import ModuleSettingsRegistry
+from settings.registration import register_module_settings
+from settings.services import SettingsServices
+from settings.settings import SettingsSettings
+
+
+class _FakeModuleServices:
+    def __init__(self, settings):
+        self.settings = settings
+
+
+@pytest.fixture
+def app() -> FastAPI:
+    app = FastAPI()
+    app.state.settings = SettingsServices(
+        settings=SettingsSettings(),
+        registry=__import__(
+            "settings.contracts.registry", fromlist=["SettingsRegistry"]
+        ).SettingsRegistry(),
+        module_registry=ModuleSettingsRegistry(),
+    )
+    return app
+
+
+class _UsersCfg(BaseSettings):
+    allow: bool = False
+    port: int = 25
+
+
+def test_register_installs_defaults_on_app_state(app):
+    register_module_settings(app, "users", _UsersCfg, _FakeModuleServices)
+    assert isinstance(app.state.users, _FakeModuleServices)
+    assert app.state.users.settings == _UsersCfg()
+
+
+def test_register_adds_to_module_registry(app):
+    register_module_settings(app, "users", _UsersCfg, _FakeModuleServices)
+    assert app.state.settings.module_registry.get("users") is _UsersCfg
+
+
+def test_register_duplicate_raises(app):
+    register_module_settings(app, "users", _UsersCfg, _FakeModuleServices)
+    with pytest.raises(ValueError, match="already registered"):
+        register_module_settings(app, "users", _UsersCfg, _FakeModuleServices)
diff --git a/modules/settings/tests/test_reload.py b/modules/settings/tests/test_reload.py
new file mode 100644
index 00000000..29f2bb74
--- /dev/null
+++ b/modules/settings/tests/test_reload.py
@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import pytest
+from fastapi import FastAPI
+from pydantic import ValidationError
+from pydantic_settings import BaseSettings
+from settings.contracts.events import SettingsReloaded
+from settings.registration import register_module_settings
+from settings.reload import apply_changes_and_reload
+from settings.service import SettingService
+from settings.services import SettingsServices
+from settings.settings import SettingsSettings
+from settings.store import SettingsStore
+from simple_module_core.events import EventBus
+
+
+class _UsersCfg(BaseSettings):
+    allow_signup: bool = False
+    smtp_port: int = 25
+
+
+@dataclass
+class _UsersServices:
+    settings: _UsersCfg
+
+
+@pytest.fixture
+def app_and_bus(db_session) -> tuple[FastAPI, EventBus]:
+    bus = EventBus()
+    app = FastAPI()
+    app.state.settings = SettingsServices(settings=SettingsSettings())
+    register_module_settings(app, "users", _UsersCfg, lambda s: _UsersServices(settings=s))
+    return app, bus
+
+
+@pytest.mark.asyncio
+async def test_apply_changes_updates_app_state_and_fires_event(app_and_bus, db_session):
+    app, bus = app_and_bus
+    received: list[SettingsReloaded] = []
+
+    async def handler(evt: SettingsReloaded) -> None:
+        received.append(evt)
+
+    bus.subscribe(SettingsReloaded, handler)
+
+    store = SettingsStore(SettingService(db_session))
+    new_settings = await apply_changes_and_reload(
+        app,
+        bus,
+        store,
+        package="users",
+        changes={"allow_signup": True, "smtp_port": 587},
+    )
+
+    assert new_settings.allow_signup is True
+    assert new_settings.smtp_port == 587
+    assert app.state.users.settings is new_settings
+    assert received == [SettingsReloaded(package="users", changed=("allow_signup", "smtp_port"))]
+
+    persisted = await store.get_overrides("users")
+    assert persisted == {"allow_signup": ("True", "bool"), "smtp_port": ("587", "int")}
+
+
+@pytest.mark.asyncio
+async def test_apply_changes_validation_error_rolls_back(app_and_bus, db_session):
+    app, bus = app_and_bus
+    store = SettingsStore(SettingService(db_session))
+
+    original = app.state.users.settings
+
+    with pytest.raises(ValidationError):
+        await apply_changes_and_reload(
+            app,
+            bus,
+            store,
+            package="users",
+            changes={"smtp_port": "not-an-int"},
+        )
+
+    assert app.state.users.settings is original
+    assert await store.get_overrides("users") == {}
+
+
+@pytest.mark.asyncio
+async def test_apply_changes_unknown_package_raises(app_and_bus, db_session):
+    app, bus = app_and_bus
+    store = SettingsStore(SettingService(db_session))
+
+    with pytest.raises(KeyError):
+        await apply_changes_and_reload(
+            app,
+            bus,
+            store,
+            package="unknown",
+            changes={"x": 1},
+        )
diff --git a/modules/settings/tests/test_settings_events.py b/modules/settings/tests/test_settings_events.py
new file mode 100644
index 00000000..d39ebe0e
--- /dev/null
+++ b/modules/settings/tests/test_settings_events.py
@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+import pytest
+from settings.contracts.events import SettingsReloaded
+from simple_module_core.events import EventBus
+
+
+@pytest.mark.asyncio
+async def test_publish_and_subscribe() -> None:
+    bus = EventBus()
+    received: list[SettingsReloaded] = []
+
+    async def handler(evt: SettingsReloaded) -> None:
+        received.append(evt)
+
+    bus.subscribe(SettingsReloaded, handler)
+    await bus.publish(SettingsReloaded(package="users", changed=("allow_signup",)))
+    assert received == [SettingsReloaded(package="users", changed=("allow_signup",))]
diff --git a/modules/settings/tests/test_store.py b/modules/settings/tests/test_store.py
new file mode 100644
index 00000000..eb7651d7
--- /dev/null
+++ b/modules/settings/tests/test_store.py
@@ -0,0 +1,56 @@
+"""Round-trip tests for SettingsStore — namespaced k/v over the Setting table."""
+
+from __future__ import annotations
+
+import pytest
+from settings.service import SettingService
+from settings.store import SettingsStore
+
+
+@pytest.mark.asyncio
+async def test_set_and_get_overrides(db_session) -> None:
+    store = SettingsStore(SettingService(db_session))
+    await store.set_override("users", "allow_signup", "true", "bool")
+    await store.set_override("users", "smtp_port", "587", "int")
+    await store.set_override("background_tasks", "retention_days", "30", "int")
+
+    users = await store.get_overrides("users")
+    assert users == {
+        "allow_signup": ("true", "bool"),
+        "smtp_port": ("587", "int"),
+    }
+    bg = await store.get_overrides("background_tasks")
+    assert bg == {"retention_days": ("30", "int")}
+
+
+@pytest.mark.asyncio
+async def test_set_override_updates_existing(db_session) -> None:
+    store = SettingsStore(SettingService(db_session))
+    await store.set_override("users", "allow_signup", "true", "bool")
+    await store.set_override("users", "allow_signup", "false", "bool")
+
+    assert await store.get_overrides("users") == {"allow_signup": ("false", "bool")}
+
+
+@pytest.mark.asyncio
+async def test_clear_override(db_session) -> None:
+    store = SettingsStore(SettingService(db_session))
+    await store.set_override("users", "allow_signup", "true", "bool")
+    await store.clear_override("users", "allow_signup")
+
+    assert await store.get_overrides("users") == {}
+
+
+@pytest.mark.asyncio
+async def test_clear_override_missing_is_noop(db_session) -> None:
+    store = SettingsStore(SettingService(db_session))
+    await store.clear_override("users", "does_not_exist")  # must not raise
+
+
+@pytest.mark.asyncio
+async def test_list_packages_with_overrides(db_session) -> None:
+    store = SettingsStore(SettingService(db_session))
+    await store.set_override("users", "allow_signup", "true", "bool")
+    await store.set_override("background_tasks", "retention_days", "7", "int")
+
+    assert await store.list_packages_with_overrides() == ["background_tasks", "users"]
diff --git a/modules/users/tests/conftest.py b/modules/users/tests/conftest.py
index 19a85ac3..3b346583 100644
--- a/modules/users/tests/conftest.py
+++ b/modules/users/tests/conftest.py
@@ -24,19 +24,13 @@
 
 @pytest.fixture(autouse=True)
 def _isolate_users_env(monkeypatch):
-    """Insulate every users-module test from the repo's real ``.env``.
-
-    Local development sets ``SM_USERS_BOOTSTRAP_EMAIL`` (and similar) in
-    ``.env`` so the dev login page can offer quick-login buttons. When
-    pytest runs in that checkout, pydantic-settings loads those values and
-    they leak into tests asserting defaults or empty-table behavior. We
-    turn off the dotenv load and scrub any leftover ``SM_USERS_*`` from
-    ``os.environ``; fixtures that need specific values then set them
-    explicitly via ``monkeypatch.setenv``.
-    """
-    from users.settings import UsersSettings
+    """Scrub stale ``SM_USERS_*`` env vars from the shell/.env.
 
-    monkeypatch.setitem(UsersSettings.model_config, "env_file", None)
+    After the env→DB migration ``UsersSettings()`` no longer reads these
+    values, so this is belt-and-braces: it keeps old shell exports from
+    muddying any ``SM_ENVIRONMENT`` checks or from being misread during
+    developer spelunking.
+    """
     for key in list(os.environ):
         if key.startswith("SM_USERS_"):
             monkeypatch.delenv(key, raising=False)
@@ -47,18 +41,19 @@ def _isolate_users_env(monkeypatch):
 # ---------------------------------------------------------------------------
 
 
-def _users_env(allow_signup: bool = False) -> dict:
+def _users_overrides(allow_signup: bool = False) -> dict[str, tuple[str, str]]:
+    """Values seeded into the ``SettingsStore`` before the app lifespan runs."""
     return {
-        "SM_USERS_ALLOW_SIGNUP": str(allow_signup).lower(),
-        "SM_USERS_MAILER": "console",
-        "SM_USERS_BASE_URL": "http://testserver",
-        "SM_USERS_COOKIE_SECURE": "false",
+        "allow_signup": (str(allow_signup).lower(), "bool"),
+        "mailer": ("console", "string"),
+        "base_url": ("http://testserver", "string"),
+        "cookie_secure": ("false", "bool"),
         # 32+ bytes to clear pyjwt's InsecureKeyLengthWarning for HMAC-SHA256.
-        "SM_USERS_RESET_PASSWORD_TOKEN_SECRET": "test-reset-secret-32-bytes-xxxxx",
-        "SM_USERS_VERIFICATION_TOKEN_SECRET": "test-verify-secret-32-bytes-xxxxx",
-        "SM_USERS_LOGIN_RATE_LIMIT_FAILURES": "5",
-        "SM_USERS_LOGIN_RATE_LIMIT_WINDOW_SECONDS": "300",
-        "SM_USERS_LOGIN_RATE_LIMIT_COOLDOWN_SECONDS": "900",
+        "reset_password_token_secret": ("test-reset-secret-32-bytes-xxxxx", "string"),
+        "verification_token_secret": ("test-verify-secret-32-bytes-xxxxx", "string"),
+        "login_rate_limit_failures": ("5", "int"),
+        "login_rate_limit_window_seconds": ("300", "int"),
+        "login_rate_limit_cooldown_seconds": ("900", "int"),
     }
 
 
@@ -112,13 +107,26 @@ async def _seed_roles(application) -> None:
         await session.commit()
 
 
+async def _seed_users_settings(application, *, allow_signup: bool) -> None:
+    """Write the test UsersSettings overrides to the DB before hydrate runs.
+
+    Hydrate fires inside the lifespan ``__aenter__``, so this needs to land
+    between table creation and lifespan entry.
+    """
+    from settings.service import SettingService
+    from settings.store import SettingsStore
+
+    async with application.state.sm.db.session_factory() as session:
+        store = SettingsStore(SettingService(session))
+        for field, (raw, vtype) in _users_overrides(allow_signup=allow_signup).items():
+            await store.set_override("users", field, raw, vtype)
+        await session.commit()
+
+
 async def _build_users_app(monkeypatch, *, allow_signup: bool):
-    """Build a test FastAPI app with env patched, DB created, lifespan started."""
+    """Build a test FastAPI app with DB created, settings seeded, lifespan started."""
     from simple_module_hosting.app_builder import create_app
 
-    for k, v in _users_env(allow_signup=allow_signup).items():
-        monkeypatch.setenv(k, v)
-
     settings = Settings(
         database_url="sqlite+aiosqlite:///:memory:",
         environment="testing",
@@ -127,6 +135,7 @@ async def _build_users_app(monkeypatch, *, allow_signup: bool):
     )
     application = create_app(settings)
     await _setup_app_db(application)
+    await _seed_users_settings(application, allow_signup=allow_signup)
 
     ctx = application.router.lifespan_context(application)
     await ctx.__aenter__()
diff --git a/modules/users/tests/test_settings.py b/modules/users/tests/test_settings.py
index 53c1c19a..bc628197 100644
--- a/modules/users/tests/test_settings.py
+++ b/modules/users/tests/test_settings.py
@@ -51,30 +51,57 @@ def test_bootstrap_email_default_empty(self):
         assert s.bootstrap_email == ""
 
 
-class TestUsersSettingsEnvVars:
-    def test_allow_signup_from_env(self, monkeypatch):
-        monkeypatch.setenv("SM_USERS_ALLOW_SIGNUP", "true")
+class TestUsersSettingsDbOverrides:
+    """After the env→DB migration these values come through ``hydrate_settings``."""
 
+    @pytest.mark.asyncio
+    async def test_allow_signup_override_from_db(self, db_session):
+        from settings.hydrate import hydrate_settings
+        from settings.service import SettingService
+        from settings.store import SettingsStore
         from users.settings import UsersSettings
 
-        s = UsersSettings()
-        assert s.allow_signup is True
+        store = SettingsStore(SettingService(db_session))
+        await store.set_override("users", "allow_signup", "true", "bool")
 
-    def test_mailer_smtp_from_env(self, monkeypatch):
-        monkeypatch.setenv("SM_USERS_MAILER", "smtp")
+        cfg = await hydrate_settings(UsersSettings, store, "users")
+        assert cfg.allow_signup is True
 
+    @pytest.mark.asyncio
+    async def test_mailer_override_from_db(self, db_session):
+        from settings.hydrate import hydrate_settings
+        from settings.service import SettingService
+        from settings.store import SettingsStore
         from users.settings import UsersSettings
 
-        s = UsersSettings()
-        assert s.mailer == "smtp"
+        store = SettingsStore(SettingService(db_session))
+        await store.set_override("users", "mailer", "smtp", "string")
 
-    def test_base_url_from_env(self, monkeypatch):
-        monkeypatch.setenv("SM_USERS_BASE_URL", "https://example.com")
+        cfg = await hydrate_settings(UsersSettings, store, "users")
+        assert cfg.mailer == "smtp"
 
+    @pytest.mark.asyncio
+    async def test_base_url_override_from_db(self, db_session):
+        from settings.hydrate import hydrate_settings
+        from settings.service import SettingService
+        from settings.store import SettingsStore
+        from users.settings import UsersSettings
+
+        store = SettingsStore(SettingService(db_session))
+        await store.set_override("users", "base_url", "https://example.com", "string")
+
+        cfg = await hydrate_settings(UsersSettings, store, "users")
+        assert cfg.base_url == "https://example.com"
+
+    def test_env_vars_are_ignored(self, monkeypatch):
+        """Setting SM_USERS_* must not affect UsersSettings() after the migration."""
+        monkeypatch.setenv("SM_USERS_ALLOW_SIGNUP", "true")
+        monkeypatch.setenv("SM_USERS_MAILER", "smtp")
         from users.settings import UsersSettings
 
         s = UsersSettings()
-        assert s.base_url == "https://example.com"
+        assert s.allow_signup is False
+        assert s.mailer == "console"
 
 
 class TestUsersSettingsValidation:
@@ -112,30 +139,29 @@ def test_placeholder_secrets_ok_in_testing(self, monkeypatch):
 
     def test_placeholder_reset_secret_rejected_in_production(self, monkeypatch):
         monkeypatch.setenv("SM_ENVIRONMENT", "production")
-        monkeypatch.setenv(
-            "SM_USERS_VERIFICATION_TOKEN_SECRET", "not-a-placeholder-value-just-for-test"
-        )
         from users.settings import UsersSettings
 
         with pytest.raises(ValidationError, match="RESET_PASSWORD_TOKEN_SECRET"):
-            UsersSettings()
+            UsersSettings(
+                verification_token_secret="not-a-placeholder-value-just-for-test",
+            )
 
     def test_placeholder_verify_secret_rejected_in_production(self, monkeypatch):
         monkeypatch.setenv("SM_ENVIRONMENT", "production")
-        monkeypatch.setenv(
-            "SM_USERS_RESET_PASSWORD_TOKEN_SECRET", "not-a-placeholder-value-just-for-test"
-        )
         from users.settings import UsersSettings
 
         with pytest.raises(ValidationError, match="VERIFICATION_TOKEN_SECRET"):
-            UsersSettings()
+            UsersSettings(
+                reset_password_token_secret="not-a-placeholder-value-just-for-test",
+            )
 
     def test_real_secrets_accepted_in_production(self, monkeypatch):
         monkeypatch.setenv("SM_ENVIRONMENT", "production")
-        monkeypatch.setenv("SM_USERS_RESET_PASSWORD_TOKEN_SECRET", "real-reset-secret")
-        monkeypatch.setenv("SM_USERS_VERIFICATION_TOKEN_SECRET", "real-verify-secret")
         from users.settings import UsersSettings
 
-        s = UsersSettings()
+        s = UsersSettings(
+            reset_password_token_secret="real-reset-secret",
+            verification_token_secret="real-verify-secret",
+        )
         assert s.reset_password_token_secret == "real-reset-secret"
         assert s.verification_token_secret == "real-verify-secret"
diff --git a/modules/users/users/bootstrap.py b/modules/users/users/bootstrap.py
index db58ed73..9bb06e8c 100644
--- a/modules/users/users/bootstrap.py
+++ b/modules/users/users/bootstrap.py
@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import logging
+import os
 from dataclasses import dataclass
 
 from fastapi import FastAPI
@@ -189,7 +190,19 @@ async def bootstrap_admin_from_env(app: FastAPI) -> None:
     useful in dev for testing non-admin flows alongside the admin account.
     """
     settings: UsersSettings = app.state.users.settings
-    if not settings.bootstrap_email or not settings.bootstrap_password:
+    # Bootstrap fields are one-shot seed inputs, not runtime DB settings —
+    # prefer the settings value if a test set one explicitly, otherwise fall
+    # back to the env var so production deployments keep working.
+    email = settings.bootstrap_email or os.environ.get("SM_USERS_BOOTSTRAP_EMAIL", "")
+    password = settings.bootstrap_password or os.environ.get("SM_USERS_BOOTSTRAP_PASSWORD", "")
+    user_email = settings.bootstrap_user_email or os.environ.get(
+        "SM_USERS_BOOTSTRAP_USER_EMAIL", ""
+    )
+    user_password = settings.bootstrap_user_password or os.environ.get(
+        "SM_USERS_BOOTSTRAP_USER_PASSWORD", ""
+    )
+
+    if not email or not password:
         return
 
     session_factory = app.state.sm.db.session_factory
@@ -199,16 +212,12 @@ async def bootstrap_admin_from_env(app: FastAPI) -> None:
             return
 
         try:
-            await create_admin(
-                session,
-                email=settings.bootstrap_email,
-                password=settings.bootstrap_password,
-            )
-            if settings.bootstrap_user_email and settings.bootstrap_user_password:
+            await create_admin(session, email=email, password=password)
+            if user_email and user_password:
                 await create_standard_user(
                     session,
-                    email=settings.bootstrap_user_email,
-                    password=settings.bootstrap_user_password,
+                    email=user_email,
+                    password=user_password,
                 )
         except Exception:
             logger.exception(_EVT_FAILED)
diff --git a/modules/users/users/endpoints/api.py b/modules/users/users/endpoints/api.py
index 049c4ceb..73b17b06 100644
--- a/modules/users/users/endpoints/api.py
+++ b/modules/users/users/endpoints/api.py
@@ -65,6 +65,17 @@ async def enforce_auth_throughput_limit(request: Request) -> None:
         )
 
 
+async def require_signup_enabled(request: Request) -> None:
+    """Gate the register endpoint at request time on ``allow_signup``.
+
+    Mounting stays unconditional so settings reloads don't need to rebuild
+    the router. When signup is disabled we return 404 so the endpoint
+    appears absent (matches the view-side behaviour at ``/users/register``).
+    """
+    if not request.app.state.users.settings.allow_signup:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND)
+
+
 # ── Wrapper login ────────────────────────────────────────────────────────────
 
 
@@ -114,8 +125,8 @@ async def login(
 router.include_router(auth_inner, prefix="/auth-inner")
 
 
-def register_auth_routes(api_router: APIRouter, settings) -> None:
-    """Mount all auth routes, conditionally adding register if allowed.
+def register_auth_routes(api_router: APIRouter) -> None:
+    """Mount all auth routes.
 
     The stock fastapi-users routers (reset/verify/register) ship POST endpoints
     that trigger email side-effects or account creation. We wrap them with the
@@ -123,6 +134,9 @@ def register_auth_routes(api_router: APIRouter, settings) -> None:
     accounts indefinitely. ``router`` itself is left unwrapped because its
     rate-limited endpoints apply the dep themselves (login via LoginRateLimiter,
     accept-invite via ``enforce_auth_throughput_limit``).
+
+    The register router is always mounted; ``require_signup_enabled`` gates
+    it at request time so ``allow_signup`` is hot-reloadable.
     """
     api_router.include_router(router)
     api_router.include_router(
@@ -137,13 +151,15 @@ def register_auth_routes(api_router: APIRouter, settings) -> None:
         tags=["users-auth"],
         dependencies=[Depends(enforce_auth_throughput_limit)],
     )
-    if settings.allow_signup:
-        api_router.include_router(
-            fastapi_users.get_register_router(UserRead, UserCreate),
-            prefix="/auth",
-            tags=["users-auth"],
-            dependencies=[Depends(enforce_auth_throughput_limit)],
-        )
+    api_router.include_router(
+        fastapi_users.get_register_router(UserRead, UserCreate),
+        prefix="/auth",
+        tags=["users-auth"],
+        dependencies=[
+            Depends(require_signup_enabled),
+            Depends(enforce_auth_throughput_limit),
+        ],
+    )
 
 
 # ── Accept-invite (verify + set password + login, one shot) ─────────────────
diff --git a/modules/users/users/endpoints/views.py b/modules/users/users/endpoints/views.py
index a79a87a3..333df581 100644
--- a/modules/users/users/endpoints/views.py
+++ b/modules/users/users/endpoints/views.py
@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import os
 import uuid
 
 from fastapi import APIRouter, Depends, HTTPException, Request
@@ -47,22 +48,24 @@ async def login_page(request: Request, inertia: InertiaDep) -> InertiaResponse:
     # production, regardless of whether the vars are set.
     dev_accounts: list[dict[str, str]] = []
     if request.app.state.sm.settings.is_development:
-        if users_settings.bootstrap_email and users_settings.bootstrap_password:
+        admin_email = users_settings.bootstrap_email or os.environ.get(
+            "SM_USERS_BOOTSTRAP_EMAIL", ""
+        )
+        admin_password = users_settings.bootstrap_password or os.environ.get(
+            "SM_USERS_BOOTSTRAP_PASSWORD", ""
+        )
+        if admin_email and admin_password:
             dev_accounts.append(
-                {
-                    "label": "Admin",
-                    "email": users_settings.bootstrap_email,
-                    "password": users_settings.bootstrap_password,
-                }
-            )
-        if users_settings.bootstrap_user_email and users_settings.bootstrap_user_password:
-            dev_accounts.append(
-                {
-                    "label": "User",
-                    "email": users_settings.bootstrap_user_email,
-                    "password": users_settings.bootstrap_user_password,
-                }
+                {"label": "Admin", "email": admin_email, "password": admin_password}
             )
+        user_email = users_settings.bootstrap_user_email or os.environ.get(
+            "SM_USERS_BOOTSTRAP_USER_EMAIL", ""
+        )
+        user_password = users_settings.bootstrap_user_password or os.environ.get(
+            "SM_USERS_BOOTSTRAP_USER_PASSWORD", ""
+        )
+        if user_email and user_password:
+            dev_accounts.append({"label": "User", "email": user_email, "password": user_password})
     return await inertia.render(
         _PAGE_LOGIN,
         {"allow_signup": users_settings.allow_signup, "dev_accounts": dev_accounts},
diff --git a/modules/users/users/module.py b/modules/users/users/module.py
index d763e316..390c0f83 100644
--- a/modules/users/users/module.py
+++ b/modules/users/users/module.py
@@ -41,13 +41,22 @@ class UsersModule(ModuleBase):
     )
 
     def register_settings(self, app: FastAPI) -> None:
+        import importlib
+
         from auth.contracts.schemas import UserContext
 
         from users.settings import UsersSettings
         from users.state import UsersState
 
-        state = UsersState(settings=UsersSettings())
-        app.state.users = state
+        # SM009 is AST-based: a static `from settings.registration import ...`
+        # from a module helper is fine (plugin→plugin), but we resolve via
+        # importlib here to match the convention used framework-side and to
+        # keep the dependency direction one-way explicit.
+        register_module_settings = importlib.import_module(
+            "settings.registration"
+        ).register_module_settings
+
+        register_module_settings(app, "users", UsersSettings, lambda s: UsersState(settings=s))
 
         def serialize_principal(user: UserContext) -> dict:
             return {
@@ -102,11 +111,11 @@ def register_menu_items(self, registry: MenuRegistry) -> None:
     def register_routes(self, api_router: APIRouter, view_router: APIRouter) -> None:
         from users.endpoints.api import register_auth_routes
         from users.endpoints.views import router as views
-        from users.settings import UsersSettings
 
-        # UsersSettings reads from env every time — safe and idempotent.
-        # app.state is not accessible here so we re-parse from environment.
-        register_auth_routes(api_router, UsersSettings())
+        # The register router is always mounted; its `allow_signup` gate lives
+        # on a per-request dependency, so toggling the setting at runtime takes
+        # effect without needing to remount.
+        register_auth_routes(api_router)
         view_router.include_router(views)
 
     def register_middleware(self, app: FastAPI) -> None:
diff --git a/modules/users/users/settings.py b/modules/users/users/settings.py
index a2a26964..3e6cba57 100644
--- a/modules/users/users/settings.py
+++ b/modules/users/users/settings.py
@@ -1,4 +1,14 @@
-"""Users module settings loaded from SM_USERS_* environment variables."""
+"""Users module settings — DB-backed via ``register_module_settings``.
+
+Construction no longer reads ``SM_USERS_*`` environment variables. Values
+come from pydantic defaults at boot, then get hydrated from the DB by the
+hosting lifespan before module ``on_startup`` runs. Runtime changes go
+through ``settings.reload.apply_changes_and_reload``.
+
+The one remaining env read is ``SM_ENVIRONMENT``, consulted by the
+``@model_validator`` to refuse placeholder token secrets in production —
+that's a host-level setting, not a users-module field.
+"""
 
 from __future__ import annotations
 
@@ -15,7 +25,7 @@
 class UsersSettings(BaseSettings):
     """Local user management configuration."""
 
-    model_config = SettingsConfigDict(env_prefix="SM_USERS_", env_file=".env", extra="ignore")
+    model_config = SettingsConfigDict(extra="ignore")
 
     # Self-service signup
     allow_signup: bool = False
@@ -76,13 +86,13 @@ def _forbid_placeholder_token_secrets_in_production(self) -> UsersSettings:
             return self
         bad = []
         if self.reset_password_token_secret == _PLACEHOLDER_RESET_SECRET:
-            bad.append("SM_USERS_RESET_PASSWORD_TOKEN_SECRET")
+            bad.append("RESET_PASSWORD_TOKEN_SECRET")
         if self.verification_token_secret == _PLACEHOLDER_VERIFY_SECRET:
-            bad.append("SM_USERS_VERIFICATION_TOKEN_SECRET")
+            bad.append("VERIFICATION_TOKEN_SECRET")
         if bad:
             names = ", ".join(bad)
             raise ValueError(
-                f"{names} must be set to non-default value(s) when "
+                f"users.{names} must be set to non-default value(s) when "
                 f"SM_ENVIRONMENT={env!r}. Generate with "
                 "`python -c 'import secrets; print(secrets.token_urlsafe(48))'`."
             )
diff --git a/packages/i18n/src/generated-resources.ts b/packages/i18n/src/generated-resources.ts
index aaa7822f..83c7498a 100644
--- a/packages/i18n/src/generated-resources.ts
+++ b/packages/i18n/src/generated-resources.ts
@@ -313,10 +313,13 @@ export default {
     'settings.form.value_placeholder': '',
     'settings.form.value_type_label': '',
     'settings.modules.back_link': '',
+    'settings.modules.browse_free_form_link': '',
     'settings.modules.browse_link': '',
     'settings.modules.description': '',
     'settings.modules.empty_title': '',
+    'settings.modules.field_count_suffix': '',
     'settings.modules.no_fields': '',
+    'settings.modules.search_placeholder': '',
     'settings.modules.secret_badge': '',
     'settings.modules.table.default': '',
     'settings.modules.table.description': '',
diff --git a/packages/i18n/src/keys.generated.ts b/packages/i18n/src/keys.generated.ts
index 5c3f479a..4bef4f62 100644
--- a/packages/i18n/src/keys.generated.ts
+++ b/packages/i18n/src/keys.generated.ts
@@ -439,10 +439,13 @@ export const keys = {
     },
     modules: {
       back_link: 'settings.modules.back_link',
+      browse_free_form_link: 'settings.modules.browse_free_form_link',
       browse_link: 'settings.modules.browse_link',
       description: 'settings.modules.description',
       empty_title: 'settings.modules.empty_title',
+      field_count_suffix: 'settings.modules.field_count_suffix',
       no_fields: 'settings.modules.no_fields',
+      search_placeholder: 'settings.modules.search_placeholder',
       secret_badge: 'settings.modules.secret_badge',
       table: {
         default: 'settings.modules.table.default',
diff --git a/tests/e2e/test_settings_ui.py b/tests/e2e/test_settings_ui.py
new file mode 100644
index 00000000..946e19bd
--- /dev/null
+++ b/tests/e2e/test_settings_ui.py
@@ -0,0 +1,61 @@
+"""E2E smoke test for the Settings modules admin UI.
+
+Drives a real browser through the sidebar layout at ``/settings/modules``,
+toggles a module setting, and verifies the change hot-reloads into
+``app.state`` without a server restart by exercising a downstream endpoint
+whose behaviour flips when the setting flips.
+"""
+
+from __future__ import annotations
+
+import re
+
+import pytest
+from playwright.sync_api import Page, expect
+
+pytestmark = pytest.mark.e2e
+
+
+def _login(page: Page, username: str, password: str) -> None:
+    page.get_by_role("link", name="Get Started").first.click()
+    page.locator("#email").fill(username)
+    page.locator("#password").fill(password)
+    page.get_by_role("button", name="Sign in").click()
+    # Wait for the session cookie to land before navigating away, or
+    # /settings/modules bounces us back to login and the sidebar never renders.
+    page.wait_for_url("**/dashboard/**", timeout=15_000)
+
+
+def test_toggle_host_multi_tenant_persists(
+    page: Page, e2e_username: str, e2e_password: str
+) -> None:
+    """Toggle ``host.multi_tenant`` from the admin UI and confirm the PUT
+    succeeds (surfaced by the Save button going idle). Proves the typed
+    settings form wires up to the REST API."""
+    page.goto("/")
+    _login(page, e2e_username, e2e_password)
+
+    page.goto("/settings/modules")
+    expect(page.get_by_text("Host", exact=False)).to_be_visible()
+
+    # Click the Host entry in the sidebar.
+    page.get_by_role("button", name=re.compile(r"host", re.I)).first.click()
+
+    checkbox = page.get_by_role("checkbox").first
+    before = checkbox.is_checked()
+    checkbox.click()
+
+    save = page.get_by_role("button", name="Save")
+    expect(save).to_be_enabled()
+    save.click()
+
+    # On success the form resets dirty state → Save becomes disabled again.
+    expect(save).to_be_disabled()
+
+    # Toggle back so the test is idempotent.
+    checkbox.click()
+    expect(save).to_be_enabled()
+    save.click()
+    expect(save).to_be_disabled()
+
+    assert page.get_by_role("checkbox").first.is_checked() == before
diff --git a/tests/test_bootstrap_settings.py b/tests/test_bootstrap_settings.py
new file mode 100644
index 00000000..09d60883
--- /dev/null
+++ b/tests/test_bootstrap_settings.py
@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+import pytest
+from simple_module_hosting.bootstrap_settings import BootstrapSettings
+from simple_module_hosting.host_settings import HostSettings
+
+
+def test_bootstrap_reads_from_env(monkeypatch):
+    monkeypatch.setenv("SM_DATABASE_URL", "sqlite+aiosqlite:///:memory:")
+    monkeypatch.setenv("SM_SECRET_KEY", "x" * 48)
+    monkeypatch.setenv("SM_ENVIRONMENT", "development")
+    bs = BootstrapSettings()
+    assert bs.database_url == "sqlite+aiosqlite:///:memory:"
+    assert bs.secret_key == "x" * 48
+    assert bs.environment == "development"
+
+
+def test_bootstrap_placeholder_secret_blocks_production(monkeypatch):
+    monkeypatch.setenv("SM_ENVIRONMENT", "production")
+    monkeypatch.setenv("SM_SECRET_KEY", "change-me-in-production")
+    with pytest.raises(ValueError, match="SM_SECRET_KEY"):
+        BootstrapSettings()
+
+
+def test_host_settings_ignores_env(monkeypatch):
+    # HostSettings must NOT read env — env-sprawl is what we're removing.
+    monkeypatch.setenv("SM_MULTI_TENANT", "true")
+    hs = HostSettings()
+    assert hs.multi_tenant is False  # default wins; env ignored
+
+
+def test_host_settings_default_locale_must_be_supported():
+    with pytest.raises(ValueError):
+        HostSettings(i18n_default_locale="de", i18n_supported_locales=["en"])
+
+
+@pytest.mark.asyncio
+async def test_host_settings_registered_as_host_package(app):
+    registry = app.state.settings.module_registry
+    assert registry.get("host").__name__ == "HostSettings"
+    assert isinstance(
+        app.state.host.settings,
+        __import__("simple_module_hosting.host_settings", fromlist=["HostSettings"]).HostSettings,
+    )
diff --git a/tests/test_hydration_lifespan.py b/tests/test_hydration_lifespan.py
new file mode 100644
index 00000000..1826c315
--- /dev/null
+++ b/tests/test_hydration_lifespan.py
@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+import pytest
+
+
+@pytest.mark.asyncio
+async def test_lifespan_hydrates_host_settings_from_db(app, db_session):
+    """After lifespan starts, host settings reflect DB overrides, not defaults."""
+    from settings.service import SettingService
+    from settings.store import SettingsStore
+
+    store = SettingsStore(SettingService(db_session))
+    await store.set_override("host", "multi_tenant", "true", "bool")
+
+    from simple_module_hosting._hydrate_step import hydrate_all
+
+    await hydrate_all(app, store)
+
+    assert app.state.host.settings.multi_tenant is True