diff --git a/.env.example b/.env.example
index c1472369..b624c73c 100644
--- a/.env.example
+++ b/.env.example
@@ -27,7 +27,7 @@ SM_VITE_DEV_URL=http://localhost:5050
 # SM_AUTH_PUBLIC_PATHS=["/api/integrations/webhook", "/status"]
 
 # First-boot admin seed (optional). Only applied when the users table is empty.
-# Leave unset and use `uv run sm-users create-admin` instead if you prefer.
+# Leave unset and use `uv run smpy users create-admin` instead if you prefer.
 # SM_USERS_BOOTSTRAP_EMAIL=admin@example.com
 # SM_USERS_BOOTSTRAP_PASSWORD=changeme
 # Optional second non-admin seed user (handy in dev):
diff --git a/CLAUDE.md b/CLAUDE.md
index d351c508..aadb8405 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -31,8 +31,8 @@ All day-to-day tasks go through `make`:
 | Command | Purpose |
 |---|---|
 | `make install` | Install Python + JS deps |
-| `make dev` | Docker up + regen module pages + API (8000) and Vite (5173) in parallel |
-| `make kill` | Free ports 8000/5173 |
+| `make dev` | Docker up + regen module pages + API (8000) and Vite (5050) in parallel |
+| `make kill` | Free ports 8000/5050/5173 |
 | `make test` | Run `test-py` then `test-js` (e2e excluded by default) |
 | `make test-py` / `make test-js` | Run a single suite |
 | `make test-e2e` | Playwright smoke tests (requires `make dev` running + `uv run playwright install chromium`) |
@@ -42,7 +42,7 @@ All day-to-day tasks go through `make`:
 | `make new-module name=<name>` | Scaffold a new module package end-to-end |
 | `make gen-pages` | Regenerate `host/client_app/modules.{manifest.json,generated.ts,generated.css}` from installed modules |
 
-Single test: `uv run pytest path/to/test_file.py::test_name` (root `pyproject.toml` sets `asyncio_mode=auto` and `-m 'not e2e'`). A single JS test: `npx vitest run <path>`.
+Single test: `uv run pytest path/to/test_file.py::test_name` (root `pyproject.toml` sets `asyncio_mode=auto` and `-m 'not e2e and not perf'`). A single JS test: `npx vitest run <path>`.
 
 Entry point: `host/main.py` (`uv run --project host uvicorn host.main:app --reload`). Alembic runs from the repo root (`host/alembic.ini`) so it shares the `.env` / `SM_DATABASE_URL` with the API.
 
diff --git a/README.md b/README.md
index c6cedb18..5386a1c8 100644
--- a/README.md
+++ b/README.md
@@ -1,13 +1,13 @@
 # simple_module_python
 
-A modular-monolith framework for Python. Each feature lives in its own self-contained module — its own SQLModel tables, schema, FastAPI endpoints, React pages — but everything ships as one FastAPI + Inertia.js + React app. No microservice tax, no API-client glue; just plugin modules that compose at boot.
+A modular-monolith framework for Python. Each feature lives in its own self-contained module — its own SQLModel tables, FastAPI endpoints, React pages — but everything ships as one FastAPI + Inertia.js + React app. No microservice tax, no API-client glue; just plugin modules that compose at boot.
 
 ## Stack
 
 - **Backend:** Python 3.12, FastAPI, SQLModel (SQLAlchemy async + Pydantic), Alembic
 - **Frontend:** Inertia.js + React + Tailwind CSS 4, Vite HMR
 - **UI:** shadcn/ui primitives + emerald/teal design tokens, Sora display font, DM Sans body, JetBrains Mono code
-- **Auth:** Local user management (email+password, cookie-based sessions) via fastapi-users
+- **Auth:** Pluggable providers — local users (email+password + OAuth/OIDC: Google, GitHub, Microsoft/Entra) via fastapi-users, or Keycloak OIDC SSO; cookie sessions or bearer tokens resolved through a principal-resolver chain
 - **Tooling:** uv workspaces, Ruff, ty, Biome, pytest
 
 ## Use in a new project
@@ -35,7 +35,7 @@ make install
 # 2. Copy env template (defaults work for local SQLite dev)
 cp .env.example .env
 
-# 3. Start Postgres (skip if using SQLite — the default .env uses SQLite)
+# 3. Start the shared dev-services stack — Postgres/Redis/MinIO (skip if using the default SQLite)
 make docker-up
 
 # 4. Run migrations
@@ -71,9 +71,11 @@ The new module is automatically discovered (via Python entry points), its routes
 
 ```
 framework/
+  cli/         # smpy CLI — scaffolding, skills, package updates
   core/        # module system, discovery, events, diagnostics
   db/          # per-module Base, session, mixins, listeners
   hosting/     # app_builder, middleware, settings, Inertia glue
+  testing/     # shared pytest fixtures + helpers
 modules/       # plugin modules (auth, dashboard, users, settings, ...)
 host/
   main.py      # FastAPI entry point
@@ -103,7 +105,7 @@ docs/
 | `make migration msg="..."` | Autogenerate a new migration |
 | `make new-module name=<name>` | Scaffold a new module |
 | `make kill` | Stop any running dev servers (ports 8000, 5050, 5173) |
-| `make docker-up` / `docker-down` | Manage the Postgres container (SQLite needs no Docker) |
+| `make docker-up` / `docker-down` | `docker-up` brings up the shared dev-services stack (Postgres/Redis/MinIO); `docker-down` stops only this repo's worker/beat (SQLite needs no Docker) |
 
 ## Configuration
 
@@ -202,17 +204,19 @@ SM_USERS_SMTP_TLS=true
 ## Architecture
 
 - **Modules**: discovered via Python entry points at boot. Each module subclasses `ModuleBase` and opts into the lifecycle hooks it needs (`register_routes`, `register_menu_items`, `register_permissions`, `register_middleware`, `on_startup`, ...).
-- **Database isolation**: PostgreSQL → one schema per module. SQLite → single schema, `__tablename__` prefixed with the module name.
+- **Database**: a single shared schema on both Postgres and SQLite. Each module owns its own `MetaData` (so Alembic can attribute tables to it), and `__tablename__` is prefixed with the module name (`orders_order`) to avoid collisions.
 - **Middleware pipeline** (LIFO order of execution): CorrelationId → RequestLogging → SecurityHeaders → Session → `<module middleware>` → Tenant (opt-in) → Locale → InertiaLayoutData → app.
 - **Diagnostics**: `make doctor` runs a static analyzer over installed modules looking for orphan pages, phantom renders, empty modules, framework/plugin coupling, migration drift, and locale-file consistency. Errors fail the boot in production.
 - **Internationalization**: per-module `locales/<lang>.json` files merged at boot into `I18nRegistry`. Frontend uses `i18next` with type-safe keys; backend uses `Babel` for CLDR plurals. Locale resolved per request via cookie → `Accept-Language` → `SM_I18N_DEFAULT_LOCALE`. See `docs/framework-conventions.md` → Internationalization.
 
-Deeper dives in `docs/plans/`:
+Full documentation lives in [`docs/`](docs/index.md) — a VitePress site covering the guide, framework internals, database, frontend, testing, every bundled module, and reference. When conventions are ambiguous, the authoritative single-pagers are the source of truth:
 
-- [Module lifecycle hooks](docs/superpowers/specs/2026-04-13-module-lifecycle-hooks-design.md)
-- [Alembic migrations design](docs/plans/2026-04-13-alembic-migrations-design.md)
-- [DB state refactor](docs/plans/2026-04-13-eliminate-global-mutable-db-state-design.md)
-- [DX hardening (latest)](docs/plans/2026-04-14-dx-hardening-design.md)
+- [Framework conventions](docs/framework-conventions.md)
+- [Module authoring](docs/module-authoring.md)
+- [E2E testing](docs/e2e-testing.md)
+- [Release playbook](docs/release.md)
+
+Historical, point-in-time design docs live under [`docs/plans/`](docs/plans/) and [`docs/superpowers/`](docs/superpowers/).
 
 ## Contributing
 
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index 7d76e59b..e65cfcd0 100644
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -121,6 +121,8 @@ export default defineConfig({
             { text: "Middleware pipeline", link: "/framework/middleware" },
             { text: "Settings & app.state", link: "/framework/settings" },
             { text: "Permissions", link: "/framework/permissions" },
+            { text: "Principal resolvers", link: "/framework/principal-resolvers" },
+            { text: "Public routes", link: "/framework/public-routes" },
             { text: "Events", link: "/framework/events" },
             { text: "Internationalization", link: "/framework/i18n" },
           ],
@@ -173,11 +175,13 @@ export default defineConfig({
             { text: "Overview", link: "/modules/" },
             { text: "auth", link: "/modules/auth" },
             { text: "users", link: "/modules/users" },
+            { text: "keycloak", link: "/modules/keycloak" },
             { text: "permissions", link: "/modules/permissions" },
             { text: "settings", link: "/modules/settings" },
             { text: "feature_flags", link: "/modules/feature_flags" },
             { text: "file_storage", link: "/modules/file_storage" },
             { text: "background_tasks", link: "/modules/background_tasks" },
+            { text: "audit_log", link: "/modules/audit_log" },
             { text: "dashboard", link: "/modules/dashboard" },
           ],
         },
diff --git a/docs/database/migrations.md b/docs/database/migrations.md
index 8a56fb7c..bff07a36 100644
--- a/docs/database/migrations.md
+++ b/docs/database/migrations.md
@@ -1,11 +1,11 @@
 # Migrations
 
-All migrations live in `migrations/versions/` in your app — **not** in module packages. Alembic runs from the app root (`alembic.ini`) and shares the app's `.env` / `SM_DATABASE_URL`.
+All migrations live in `host/migrations/versions/` — **not** in module packages. Alembic runs from the repo root via `host/alembic.ini` and shares the app's `.env` / `SM_DATABASE_URL`.
 
 ## Why centralized?
 
-- **Dependency ordering is global.** If `invoices` depends on `orders.order.id`, their migrations must order correctly. One linear Alembic history enforces this.
-- **Autogenerate sees everything.** `migrations/env.py` calls `build_module_metadata()` to union every installed module's `MetaData`. Autogenerate diffs the DB against that union and writes one migration covering all changes.
+- **Dependency ordering is global.** If `invoices` depends on `orders_order.id`, their migrations must order correctly. One linear Alembic history enforces this.
+- **Autogenerate sees everything.** `host/migrations/env.py` calls `build_module_metadata()` to union every installed module's `MetaData`. Autogenerate diffs the DB against that union and writes one migration covering all changes.
 - **Operators run one command.** `make migrate` is the only target. No "did you also run `orders/migrate`?" footgun.
 
 Each module's *first* migration sets `branch_labels = ("<module_name>",)` so you can still downgrade one module at a time with `alembic downgrade <module>@base`.
@@ -15,10 +15,10 @@ Each module's *first* migration sets `branch_labels = ("<module_name>",)` so you
 ### Create a migration
 
 ```bash
-uv run alembic revision --autogenerate -m "add orders tables"
+make migration msg="add orders tables"
 ```
 
-The resulting file lands in `migrations/versions/XXXX_add_orders_tables.py`.
+This runs `alembic -c host/alembic.ini revision --autogenerate` from the repo root. The resulting file lands in `host/migrations/versions/XXXX_add_orders_tables.py`.
 
 **Always open and read the generated file** before committing. Autogenerate is good but not perfect:
 
@@ -32,14 +32,14 @@ The resulting file lands in `migrations/versions/XXXX_add_orders_tables.py`.
 make migrate
 ```
 
-Runs `alembic upgrade head`. Idempotent.
+Runs `alembic -c host/alembic.ini upgrade heads`. Idempotent.
 
 ### Downgrade
 
 ```bash
-uv run alembic downgrade -1              # back one revision
-uv run alembic downgrade <revision_id>   # to a specific revision
-uv run alembic downgrade orders@base     # back to the state before the orders module existed
+make downgrade                                                 # back one revision
+uv run --project host alembic -c host/alembic.ini downgrade <revision_id>   # to a specific revision
+uv run --project host alembic -c host/alembic.ini downgrade orders@base     # back to the state before the orders module existed
 ```
 
 `orders@base` uses the `branch_labels` marker from the module's first migration. Module-level downgrade is the mechanism for uninstalling a module cleanly.
@@ -49,7 +49,7 @@ uv run alembic downgrade orders@base     # back to the state before the orders m
 When you scaffold a module with `smpy create-module`, the *first* autogenerate revision produces a file that needs this marker added by hand:
 
 ```python
-# migrations/versions/XXXX_add_orders_tables.py
+# host/migrations/versions/XXXX_add_orders_tables.py
 
 revision = "..."
 down_revision = "..."
@@ -61,27 +61,32 @@ Once the marker is in place, all future `orders` migrations inherit the branch.
 
 ## Alembic environment setup
 
-`migrations/env.py` (in your app) looks roughly like:
+`host/migrations/env.py` looks roughly like:
 
 ```python
-from simple_module_db.base import build_module_metadata
-from simple_module_db.migration_support import make_include_object
+from simple_module_db import (
+    build_module_metadata,
+    make_include_object,
+    make_process_revision_directives,
+    render_item,
+)
 
 target_metadata = build_module_metadata()
-include_object = make_include_object()
+include_object = make_include_object(target_metadata)
+process_revision_directives = make_process_revision_directives(target_metadata)
 
 context.configure(
     target_metadata=target_metadata,
     include_object=include_object,
-    compare_type=True,
-    compare_server_default=True,
+    render_item=render_item,
+    process_revision_directives=process_revision_directives,
 )
 ```
 
 - `target_metadata` — union of every module's `MetaData`.
-- `include_object` — filters out system tables (`alembic_version`) and any host-owned tables you don't want tracked.
-- `compare_type=True` — detects type changes (e.g. `VARCHAR(50)` → `VARCHAR(100)`).
-- `compare_server_default=True` — detects default-value changes.
+- `include_object` — accepts only tables present in `target_metadata`, so autogenerate never diffs system tables (`alembic_version`) or any host-owned tables outside the module system.
+- `render_item` — collapses SQLModel's `AutoString` to `sa.String` and renders `StrEnum` columns with `values_callable` so generated migrations are importable.
+- `process_revision_directives` — re-emits expression-based (functional) indexes that autogenerate silently drops under SQLite.
 
 ## Boot-time migration check
 
@@ -100,17 +105,17 @@ Fires as a warning when a module's model declares a table that doesn't appear in
 - You renamed a table but the old migration still references the old name.
 - You used `__abstract__ = True` somewhere it shouldn't be.
 
-The dev-mode boot log prints the offending table names. Resolution: run `uv run alembic revision --autogenerate -m "..."`, review, `make migrate`.
+The dev-mode boot log prints the offending table names. Resolution: run `make migration msg="..."`, review, `make migrate`.
 
 ## Cross-module foreign keys
 
-If `invoices` has an FK to `orders.order.id`:
+If `invoices` has an FK to `orders_order.id`:
 
 - Alembic will emit `ADD CONSTRAINT` in the invoices table's migration.
 - The migration that creates `invoices_invoice` must come **after** the one that creates `orders_order` in linear history.
-- `smpy create-module` + `uv run alembic revision --autogenerate` handle this naturally as long as `depends_on` is correct in `ModuleMeta`.
+- `smpy create-module` + `make migration` handle this naturally as long as `depends_on` is correct in `ModuleMeta`.
 
-On Postgres, cross-schema FKs work natively (`orders.order.id ← invoices.invoice.order_id`).
+All tables share the host's single schema on both Postgres and SQLite, so a cross-module FK is just an ordinary same-schema reference (`orders_order.id ← invoices_invoice.order_id`).
 
 On SQLite, FKs are off by default but the test suite enables them; in production SQLite use (rare), set `PRAGMA foreign_keys = ON`.
 
@@ -153,7 +158,7 @@ Keep merges small; a merge revision with its own `op.*` logic is a code smell.
 
 When you autogenerate a migration for a freshly-added module, autogenerate writes `op.create_table(...)` for every table in the module's `MetaData`. Inspect:
 
-- Are the schema / table names right for your provider (`orders.order` on Postgres vs `orders_order` on SQLite)?
+- Are the table names right (the module-prefixed `orders_order`, identical on Postgres and SQLite)?
 - Do indexes and constraints have stable names? Rename via `name=...` on the model if not.
 - Did autogenerate also pick up any **other** module's tables? That means you forgot `make migrate` after the last scaffold. Squash the file down to just this module's changes.
 
@@ -168,7 +173,7 @@ async def test_migration_up_then_down(tmp_path):
     from alembic import command
 
     db_url = f"sqlite:///{tmp_path}/migrate_test.db"
-    cfg = Config("alembic.ini")
+    cfg = Config("host/alembic.ini")
     cfg.set_main_option("sqlalchemy.url", db_url)
 
     command.upgrade(cfg, "head")
diff --git a/docs/database/mixins.md b/docs/database/mixins.md
index 3e290605..e94a12cd 100644
--- a/docs/database/mixins.md
+++ b/docs/database/mixins.md
@@ -19,18 +19,18 @@ class Order(
     ...
 ```
 
-Each mixin adds columns and attaches SQLAlchemy event listeners. The session dependency (`get_db`) wires the request user / tenant into those listeners so writes are stamped automatically.
+Each mixin adds columns; the framework's SQLAlchemy event listeners (registered once per engine in `simple_module_db.listeners`) populate them. Auth and tenant middleware push the current user / tenant into contextvars (`current_user_id`, `current_tenant_id`) that those listeners read, so writes are stamped automatically.
 
 ## `AuditMixin`
 
 Adds:
 
-- `created_at: datetime` — set on INSERT.
-- `updated_at: datetime` — set on INSERT and on every UPDATE.
-- `created_by: int | None` — stamped from `request.state.principal.user_id`.
-- `updated_by: int | None` — same, on every update.
+- `created_at: datetime` — populated both Python-side (`default_factory`) and server-side (`server_default=func.now()`), so a freshly-instantiated instance can be serialized before flush.
+- `updated_at: datetime | None` — `None` until the first UPDATE; set by the audit listener and by the column's `onupdate=func.now()`.
+- `created_by: str | None` — stamped from the `current_user_id` contextvar.
+- `updated_by: str | None` — same, on insert and on every update.
 
-A `before_insert` listener and a `before_update` listener populate these. When no principal is in scope (e.g. a migration data-migration or a boot-time seeder), `created_by` and `updated_by` stay null. The timestamps always fire.
+The `before_flush` listener populates `created_by`/`updated_by` and `updated_at`. When no principal is in scope (e.g. a migration data-migration or a boot-time seeder), `created_by` and `updated_by` stay null.
 
 Use on every table that participates in business workflows. Skip on pure enum / lookup tables.
 
@@ -40,11 +40,11 @@ Adds:
 
 - `is_deleted: bool` — default `False`.
 - `deleted_at: datetime | None`.
-- `deleted_by: int | None`.
+- `deleted_by: str | None`.
 
-On `session.delete(instance)`, a `before_delete` listener converts the delete into an UPDATE that sets the three fields. The row stays.
+On `session.delete(instance)`, the `before_flush` listener cancels the hard delete and re-adds the instance with the three fields set, so the row stays as an UPDATE.
 
-Selects auto-filter soft-deleted rows. A `before_compile` query rewrite appends `WHERE is_deleted = FALSE` to any query touching a `SoftDeleteMixin` table.
+Selects auto-filter soft-deleted rows. A `do_orm_execute` listener attaches a per-mapper `with_loader_criteria(cls, cls.is_deleted.is_(False))` to every SELECT touching a `SoftDeleteMixin` table.
 
 ### Bypass for admin / audit
 
@@ -76,40 +76,25 @@ Use sparingly — audit trails and downstream systems may depend on historical r
 
 Adds:
 
-- `tenant_id: str` — populated from `request.state.tenant_id` (set by `TenantMiddleware`).
+- `tenant_id: str | None` — Python-side optional (so callers don't have to thread the tenant through), but the **column is non-nullable**. `TenantMiddleware` sets `request.state.tenant_id` and pushes it into the `current_tenant_id` contextvar; the `before_flush` listener reads that contextvar to stamp the column.
 
 ### Automatic filtering
 
-When `SM_MULTI_TENANT=true` and a request has an active tenant, selects auto-filter: `WHERE tenant_id = :current_tenant`. The filter runs for every `SELECT` that touches a `MultiTenantMixin` table.
+When `SM_MULTI_TENANT=true` and a request has an active tenant, the `do_orm_execute` listener attaches `with_loader_criteria(cls, cls.tenant_id == tenant_id)` to every SELECT touching a `MultiTenantMixin` table.
 
 ### Automatic stamping
 
-INSERTs populate `tenant_id` from the request context. Cross-tenant writes raise `ValueError` — if a session somehow ends up with two tenants' rows, the commit fails loudly.
+INSERTs populate `tenant_id` from the `current_tenant_id` contextvar. Creating a row for a different tenant than the active one — or changing `tenant_id` on an existing row — raises `TenantIsolationError`.
 
 ### Bypass
 
-Admin operations that span tenants (billing consolidation, platform-wide reports) need to opt out:
-
-```python
-stmt = select(Order).execution_options(skip_tenant_filter=True)
-```
-
-Or run inside a context manager that clears the tenant:
-
-```python
-from simple_module_db.tenancy import no_tenant
-
-async with no_tenant():
-    rows = (await session.exec(select(Order))).all()
-```
-
-Use these escape hatches **rarely** and in well-named admin endpoints; they defeat the primary isolation guarantee.
+A row inserted outside any tenant context (no active `current_tenant_id`) is stamped `None` and, because the column is non-nullable, fails at the DB rather than silently leaking. There is no per-statement `skip_tenant_filter` option or `no_tenant()` helper today; cross-tenant admin operations run outside a tenant-scoped request (e.g. a CLI or background worker where `current_tenant_id` is unset).
 
 ## `VersionedMixin`
 
 Adds:
 
-- `version: int` — default `1`, incremented on every UPDATE via `before_update` listener.
+- `version: int` — default `1`, incremented on every UPDATE by the `before_flush` listener.
 
 Useful for optimistic concurrency control: check the version didn't change between read and write, abort if it did.
 
diff --git a/docs/database/models.md b/docs/database/models.md
index 8a71b24f..d324bebc 100644
--- a/docs/database/models.md
+++ b/docs/database/models.md
@@ -53,7 +53,7 @@ class OrderLine(Base, table=True):
     order: "Order" = Relationship(back_populates="lines")
 ```
 
-For cross-module foreign keys, use the `contracts/` schema of the target module to know the expected column shape — but remember every module manages its own migrations, so the target table must exist at migration time. Cross-module FKs also complicate module uninstall; prefer application-level references where possible.
+For cross-module foreign keys, use the `contracts/` schema of the target module to know the expected column shape — but remember migrations are centralized (one linear Alembic history under `host/migrations/`), so the target table's migration must come first. Cross-module FKs also complicate module uninstall; prefer application-level references where possible.
 
 ## DTOs (schemas)
 
@@ -132,7 +132,7 @@ class Order(Base, table=True):
 
 class OrderLine(Base, table=True):
     id: int | None = Field(default=None, primary_key=True)
-    order_id: int = Field(foreign_key="orders.order.id")
+    order_id: int = Field(foreign_key="orders_order.id")
     order: Order = Relationship(back_populates="lines")
 ```
 
diff --git a/docs/database/per-module-base.md b/docs/database/per-module-base.md
index 87dfae2c..430882f4 100644
--- a/docs/database/per-module-base.md
+++ b/docs/database/per-module-base.md
@@ -23,7 +23,7 @@ The same migrations apply to Postgres and SQLite. There is no provider branching
 
 ## The `build_module_metadata()` function
 
-Alembic's autogenerate needs a **single** `MetaData` object describing every table it should manage. Each module has its own — so `migrations/env.py` calls:
+Alembic's autogenerate needs a **single** `MetaData` object describing every table it should manage. Each module has its own — so `host/migrations/env.py` calls:
 
 ```python
 from simple_module_db.base import build_module_metadata
@@ -37,13 +37,13 @@ If a module has no `models.py`, it contributes nothing — fine. If a module has
 
 ## `make_include_object()`
 
-Alembic's `include_object` callback filters which tables `autogenerate` considers. `migrations/env.py` uses `make_include_object()` from `simple_module_db` to:
+Alembic's `include_object` callback filters which tables `autogenerate` considers. `host/migrations/env.py` calls `make_include_object(target_metadata)` from `simple_module_db` to:
 
-- **Include** tables from any discovered module's MetaData.
-- **Exclude** tables owned by the Alembic runtime itself (`alembic_version`).
-- **Exclude** host-owned tables that shouldn't be in a module migration (there are currently none, but the hook is there).
+- **Include** only tables present in the combined module `MetaData` (the allowlist is `{t.name for t in metadata.tables.values()}`).
+- **Exclude** everything else — tables owned by the Alembic runtime (`alembic_version`) and any host-owned tables that aren't part of an installed module.
+- Optionally skip unmodeled foreign-key constraints (`ignore_unmodeled_fks=True` by default) so migration-level cross-module FKs aren't dropped on every autogen run.
 
-If you write a one-off host-level table that autogenerate shouldn't track, extend `make_include_object()` — don't reach into a module's `models.py`.
+If you write a one-off host-level table that autogenerate shouldn't track, keep it out of the module metadata — `make_include_object` already excludes anything not in the allowlist.
 
 ## Naming rules
 
diff --git a/docs/database/sessions.md b/docs/database/sessions.md
index 3e2cf926..ca8941c4 100644
--- a/docs/database/sessions.md
+++ b/docs/database/sessions.md
@@ -5,13 +5,13 @@ Each request opens exactly one `AsyncSession`. The framework commits only when t
 ## The `get_db` dependency
 
 ```python
-# simple_module_db.session
-async def get_db(request: Request) -> AsyncIterator[AsyncSession]:
-    engine = request.app.state.sm.db.engine_for(...)
-    async with AsyncSession(engine) as session:
+# simple_module_db.deps
+async def get_db(request: Request) -> AsyncGenerator[AsyncSession, None]:
+    factory = request.app.state.sm.db.session_factory
+    async with factory() as session:
         try:
             yield session
-            if _has_writes(session):
+            if _has_pending_writes(session):
                 await session.commit()
             else:
                 await session.rollback()
@@ -26,7 +26,7 @@ Usage in endpoints:
 from typing import Annotated
 from fastapi import Depends
 from sqlalchemy.ext.asyncio import AsyncSession
-from simple_module_db.session import get_db
+from simple_module_db.deps import get_db
 
 SessionDep = Annotated[AsyncSession, Depends(get_db)]
 
@@ -87,26 +87,26 @@ Flushing sends the INSERT but keeps the transaction open. Rollback still works u
 
 ## Manual transactions
 
-If you need finer control — e.g. a background worker that processes many items in its own transactions — use `DatabaseState` directly:
+If you need finer control — e.g. a background worker that processes many items in its own transactions — use the `DatabaseState.session_factory` directly:
 
 ```python
-from simple_module_db.state import DatabaseState
+from simple_module_db import DatabaseState
 
 async def worker(db: DatabaseState):
-    async with db.session() as session:
+    async with db.session_factory() as session:
         async with session.begin():
             # explicit transaction block
             session.add(...)
             # commits on exit, rolls back on exception
 ```
 
-The `async with session.begin()` pattern opens a sub-transaction you control. Use it in code that runs **outside** a request scope.
+The `async with session.begin()` pattern opens a transaction you control. Use it in code that runs **outside** a request scope.
 
 ## Sessions and `MultiTenantMixin`
 
-`get_db` captures `request.state.tenant_id` into the session's `info` dict. The tenant listeners read it to filter SELECTs and stamp INSERTs. This is why sessions are **request-scoped** — sharing one across tenants would silently leak data.
+The active tenant is carried in the `current_tenant_id` contextvar (set by `TenantMiddleware`, not on the session). The tenant listeners read that contextvar to filter SELECTs and stamp INSERTs. Sessions stay **request-scoped** so they always run under the request's tenant context — sharing one across tenants would silently leak data.
 
-For cross-tenant admin ops, use `no_tenant()` context or the `skip_tenant_filter=True` execution option. See [Mixins → MultiTenantMixin](/database/mixins).
+Cross-tenant admin work runs outside a tenant-scoped request (a CLI or worker where `current_tenant_id` is unset). See [Mixins → MultiTenantMixin](/database/mixins).
 
 ## Sessions in tests
 
diff --git a/docs/e2e-testing.md b/docs/e2e-testing.md
index 2c13d4c4..50155963 100644
--- a/docs/e2e-testing.md
+++ b/docs/e2e-testing.md
@@ -1,9 +1,10 @@
 # End-to-End Testing
 
 Playwright-driven smoke tests live in [tests/e2e/](../tests/e2e/) — currently
-just [`test_settings_ui.py`](../tests/e2e/test_settings_ui.py), which logs in,
-navigates to `/settings/modules`, toggles a module setting, and verifies the
-change hot-reloads into `app.state` without a server restart.
+[`test_settings_ui.py`](../tests/e2e/test_settings_ui.py) (logs in, navigates to
+`/settings/modules`, toggles a module setting, and verifies the change
+hot-reloads into `app.state` without a server restart) and
+[`test_audit_log_ui.py`](../tests/e2e/test_audit_log_ui.py).
 
 End-to-end tests are gated behind the `e2e` pytest marker (declared in
 your app's `pyproject.toml`) and are **excluded from the default
@@ -21,7 +22,7 @@ uv run playwright install chromium
 Then bring up the full stack (in a separate terminal, leave it running):
 
 ```bash
-docker compose up -d postgres   # skip if you're on the default SQLite config
+make docker-up                  # shared dev-services stack (Postgres/Redis/MinIO); skip if on default SQLite
 make migrate                    # apply Alembic migrations
 make dev                        # FastAPI on :8000 + Vite on :5050
 ```
diff --git a/docs/framework-conventions.md b/docs/framework-conventions.md
index 287d8ef3..fa75ec52 100644
--- a/docs/framework-conventions.md
+++ b/docs/framework-conventions.md
@@ -20,7 +20,7 @@ modules/<name>/
     └── pages/                # *.tsx — auto-discovered by Vite
 ```
 
-Scaffold a fresh module with `smpy create-module <name> --dest modules/<name>` — it generates all of the above. Then run `uv add ./modules/<name>` to register it on your app.
+Scaffold a fresh module with `smpy create-module <name> --dest modules/<name>` — it generates a working subset (`module.py`, `services.py`, `settings.py`, `endpoints/api.py`, an empty `pages/`, plus packaging files); add `models.py`, `deps.py`, `contracts/`, `endpoints/views.py`, and `locales/` as your module needs them. Then run `uv add ./modules/<name>` to register it on your app.
 
 ## ModuleMeta
 
@@ -66,6 +66,7 @@ SecurityHeadersMiddleware
 SessionMiddleware
 <module-registered middleware>     # each module's register_middleware()
 TenantMiddleware    (if multi_tenant=True)
+LocaleMiddleware
 InertiaLayoutDataMiddleware
 # Added first → last executed
 ```
@@ -74,7 +75,7 @@ InertiaLayoutDataMiddleware
 
 ```
 CorrelationId → RequestLogging → SecurityHeaders → Session
-  → <modules> → Tenant → InertiaLayoutData → app
+  → <modules> → Tenant → Locale → InertiaLayoutData → app
 ```
 
 ### Module-registered middleware ordering
@@ -99,7 +100,8 @@ once at boot. Consumers read `request.app.state.sm.<field>` — never raw `app.s
 attributes for framework-owned state.
 
 Fields: `settings`, `db`, `event_bus`, `menu_registry`, `permissions`,
-`feature_flags`, `health_registry`, `i18n_registry`, `inertia_config`, `modules`.
+`feature_flags`, `health_registry`, `public_routes`, `i18n_registry`,
+`inertia_config`, `modules`.
 
 Two attributes are intentionally kept outside `Services`:
 
@@ -211,7 +213,7 @@ Service code should not call `session.commit()` directly. Flush for intermediate
   Sidebar items can also set `group="<Label>"` on the `MenuItem` to render under a group header. The frontend clusters consecutive items with the same group label and prints the label as a section heading; the group's position is set by the lowest-`order` item that joins it. Built-in groups are `Content`, `Administration`, and `System`. Items with no `group` (the default) render flat — Dashboard intentionally stays ungrouped above the headed groups.
 - `i18n` — active locale and translation bundle.
 
-The framework does not know the shape of `auth.user`. A module (typically `users`) registers a `principal_serializer: Callable[[user], dict]` on `app.state` during `register_settings(app)`; the middleware calls it with `request.state.user` to build the `auth.user` payload. Without a registered serializer, `auth.user` is `None` even when a user is authenticated.
+The framework does not know the shape of `auth.user`. The `auth` module registers a `principal_serializer: Callable[[UserContext], dict]` on `app.state.principal_serializer` during `register_settings(app)`; the middleware calls it with `request.state.user` to build the `auth.user` payload. Without a registered serializer, `auth.user` is `None` even when a user is authenticated.
 
 Use `InertiaDep` from `simple_module_hosting.inertia_deps` — it attaches the shared data automatically.
 
@@ -306,7 +308,7 @@ Publish from anywhere with a bus handle:
 await bus.publish(OrderPlaced(order_id=42, total=Decimal("99")))
 ```
 
-Dispatch walks the event's MRO, so subscribing to a base class delivers subclass events.
+Dispatch keys on the **exact** event class (`module.qualname`), not its MRO — subscribing to a base `Event` class does **not** receive subclass events. Subscribe to the concrete type you want.
 
 ## Diagnostic codes
 
@@ -325,6 +327,9 @@ Dispatch walks the event's MRO, so subscribing to a base class delivers subclass
 | SM014 | WARNING | Non-default locale missing keys present in the default |
 | SM015 | WARNING | Non-default locale has keys not in the default |
 | SM016 | ERROR | Locale JSON invalid or contains non-string leaves |
+| SM017 | WARNING | Module ships `pages/*.tsx` but is missing `package.json` / `tsconfig.json` |
+| SM018 | WARNING | Inertia `router.{post,patch,put,delete}()` in a page targets a JSON `/api/*` endpoint |
+| SM019 | WARNING | Module registers view routes but no menu items or permissions (unreachable in UI) |
 | SM020 | ERROR | Multiple auth provider modules installed |
 | SM021 | WARNING | No auth provider module installed |
 
@@ -343,7 +348,7 @@ class OrdersModule(ModuleBase):
         return {"orders": Path(str(importlib.resources.files(__package__) / "locales"))}
 ```
 
-`smpy create-module` scaffolds this method and a matching `locales/en.json` automatically.
+Add this method (and a matching `locales/en.json`) yourself — the `smpy create-module` scaffold does not emit a `locales/` directory.
 
 ### Key naming
 
diff --git a/docs/framework/discovery.md b/docs/framework/discovery.md
index 66b0db50..6852ef44 100644
--- a/docs/framework/discovery.md
+++ b/docs/framework/discovery.md
@@ -21,17 +21,16 @@ Entry points are registered **at install time**, not at import time. After editi
 `simple_module_core.discovery.discover_modules()`:
 
 1. Iterates `importlib.metadata.entry_points(group="simple_module")`.
-2. For each entry point, calls `.load()` to import the module's `module.py` and pull out the class.
+2. For each entry point, calls `.load()` to import the module's `module.py` and pull out the class, then instantiates it (`module_cls()`).
 3. Validates: the loaded object must be a `ModuleBase` subclass with a `meta` attribute of type `ModuleMeta`.
-4. If `SM_MODULES_ENABLED` is set, filters to only those listed.
-5. Topologically sorts by `ModuleMeta.depends_on` using a stable tiebreaker (name).
-6. Returns a tuple of `ModuleBase` **instances** (one per module, constructed with no args).
+4. If `SM_MODULES_ENABLED` is set, filters to only the modules whose `ModuleMeta.name` (case-insensitive) appears in the list.
+5. Returns a `list` of `ModuleBase` **instances** (one per module, constructed with no args). A separate `topological_sort()` call (made by `create_app`) then orders them by `ModuleMeta.depends_on` using a stable tiebreaker (name).
 
 Failures:
 
 - **Import error** (e.g. syntax error in `module.py`) — lenient mode: logged + skipped. Strict mode: raises `InvalidModuleError`.
 - **Missing `meta`** — emits `SM001`. Strict mode: raises.
-- **Duplicate `meta.name`** — emits `SM008` (error). Always fails boot, even in dev, because names are used as DB schemas/prefixes.
+- **Duplicate `meta.name`** — emits `SM008` (error). Always fails boot, even in dev, because names are used as table-name prefixes.
 - **Cycle in `depends_on`** — raises `CircularDependencyError`. Always fails boot.
 
 ## ModuleMeta
@@ -52,8 +51,7 @@ meta = ModuleMeta(
 
 The authoritative identifier. It's used for:
 
-- Postgres schema name (lowercased → `orders`).
-- SQLite table-name prefix (`orders_*`).
+- Table-name prefix (`orders_*`) — every module's tables share the host's single schema on both Postgres and SQLite, so the prefix is what keeps them collision-free.
 - Inertia page namespace (`"Orders/Browse"`).
 - Diagnostic reporter name.
 - Feature-flag and permission grouping.
@@ -72,7 +70,7 @@ A list of other modules' `meta.name` values that **must be loaded first**. The f
 
 ### `version`
 
-Semver string. Used in diagnostic output and can be surfaced in `/admin/health` to help operators correlate deployed module versions with bug reports. Not currently parsed for automated version-range checks.
+Semver string. Used in diagnostic/boot logging to help operators correlate deployed module versions with bug reports. Unless a module declares `requires_framework`, it is not parsed for automated version-range checks.
 
 ## The `simple_module` group
 
@@ -97,9 +95,9 @@ for ep in entry_points(group='simple_module'):
 
 ## Disabling modules at runtime
 
-Set `SM_MODULES_ENABLED` to a comma-separated allow-list of entry-point names. Useful for:
+Set `SM_MODULES_ENABLED` to a comma-separated allow-list of module names (matched case-insensitively against `ModuleMeta.name`). Useful for:
 
-- Running tests against a minimal world (`SM_MODULES_ENABLED=users,orders`).
+- Running tests against a minimal world (`SM_MODULES_ENABLED=Users,Orders`).
 - Temporarily disabling a misbehaving module in production without a redeploy.
 - Sharding a large app into multiple deployments (e.g. background-worker process loads only the `background_tasks` module).
 
diff --git a/docs/framework/events.md b/docs/framework/events.md
index 002e4314..f8c49de0 100644
--- a/docs/framework/events.md
+++ b/docs/framework/events.md
@@ -89,9 +89,9 @@ def _event_bus(request: Request) -> EventBus:
 EventBusDep = Annotated[EventBus, Depends(_event_bus)]
 ```
 
-## MRO dispatch
+## Exact-type dispatch
 
-The bus walks the event's MRO, so subscribing to a **base class** delivers every subclass event:
+The bus (backed by `pyee`'s `AsyncIOEventEmitter`) keys handlers by the **exact** event type — internally `f"{event_type.__module__}.{event_type.__qualname__}"`. There is **no MRO walk**: subscribing to a base class does **not** deliver subclass events. Subscribe to each concrete type you care about:
 
 ```python
 @dataclass
@@ -103,18 +103,18 @@ class OrderPlaced(OrderEvent): ...
 @dataclass
 class OrderCancelled(OrderEvent): ...
 
-bus.subscribe(OrderEvent, audit_handler)     # receives both
-bus.subscribe(OrderPlaced, specific_handler) # receives only placed
+bus.subscribe(OrderEvent, audit_handler)     # receives only OrderEvent, NOT subclasses
+bus.subscribe(OrderPlaced, specific_handler) # receives only OrderPlaced
 ```
 
-Use base-class subscriptions sparingly — they're magnets for unintended coupling when new subclasses appear.
+If you want a handler to see several event types, subscribe it to each one explicitly.
 
 ## Delivery semantics
 
-- **Synchronous** from the publisher's perspective: `await bus.publish(...)` resolves after all handlers have run (or raised).
+- **Awaited** from the publisher's perspective: `await bus.publish(...)` runs all handlers **concurrently** via `asyncio.gather` and resolves once they've all completed. (Use `publish_nowait(...)` for fire-and-forget scheduling on the loop.)
 - **In-process only.** Not delivered to other uvicorn workers, other processes, or other hosts.
 - **No persistence.** A crash mid-publish loses undelivered events.
-- **Handler failures don't stop the publisher.** The bus logs handler exceptions and continues with the next handler. The publish itself does not raise.
+- **Handler failures are isolated.** `publish` gathers with `return_exceptions=True`: each handler exception is logged and the publish itself never raises.
 
 If you need durable delivery across processes, handlers should enqueue a Celery task:
 
diff --git a/docs/framework/i18n.md b/docs/framework/i18n.md
index b0bf6818..59fd11f3 100644
--- a/docs/framework/i18n.md
+++ b/docs/framework/i18n.md
@@ -63,17 +63,24 @@ Placeholders use `{name}` syntax, identical between frontend and backend:
 Frontend:
 
 ```tsx
-import { useT } from "@simple-module-py/i18n-react";
+import { useT } from "@simple-module-py/i18n";
 const { t } = useT();
 t("orders.greeting", { name: user.name });
 ```
 
-Backend (endpoints, emails):
+Backend (endpoints, emails) — inject the request-scoped `Translator` via `TranslatorDep`, or build one directly:
 
 ```python
-from simple_module_core.i18n import get_translator
+from simple_module_hosting.i18n_deps import TranslatorDep
 
-t = get_translator(request.state.locale)
+@router.get("/greet")
+async def greet(t: TranslatorDep, ...):
+    return {"msg": t.t("orders.greeting", name=user.name)}
+
+# Or construct one explicitly:
+from simple_module_core.i18n import Translator
+t = Translator(request.app.state.sm.i18n_registry,
+               locale=request.state.locale, default_locale="en")
 t.t("orders.greeting", name=user.name)
 ```
 
@@ -120,7 +127,7 @@ Zod schemas that reference translations **must** be constructed inside a hook 
 
 ```tsx
 import { z } from "zod";
-import { useT } from "@simple-module-py/i18n-react";
+import { useT } from "@simple-module-py/i18n";
 
 // ✅ Correct — resolves against the active locale per render
 export function useProductSchema() {
diff --git a/docs/framework/lifecycle.md b/docs/framework/lifecycle.md
index edb1cce3..a318cdf7 100644
--- a/docs/framework/lifecycle.md
+++ b/docs/framework/lifecycle.md
@@ -1,6 +1,6 @@
 # Lifecycle hooks
 
-`ModuleBase` defines ten lifecycle hooks. All are no-ops by default — override the ones you need.
+`ModuleBase` defines a set of lifecycle hooks. All are no-ops by default — override the ones you need.
 
 At boot, for each module (in topological order), the framework calls them in this sequence:
 
@@ -11,6 +11,7 @@ register_permissions
 register_feature_flags
 register_event_handlers
 register_health_checks
+register_public_routes
 register_exception_handlers
 register_middleware
 register_routes
@@ -35,22 +36,21 @@ If you override this hook but don't touch `app.state.<module_lower>`, diagnostic
 
 ## `register_menu_items(registry)`
 
-Add entries to the global `MenuRegistry`. Items are grouped by `MenuSection` and role-filtered per request by `InertiaLayoutDataMiddleware`.
+Add entries to the global `MenuRegistry`. Items are grouped by `MenuSection` and filtered per request by `InertiaLayoutDataMiddleware` (by authentication state and `roles`).
 
 ```python
 def register_menu_items(self, registry: MenuRegistry) -> None:
     registry.add(MenuItem(
         section=MenuSection.SIDEBAR,
-        key="orders",
-        label_key="orders.menu.orders",     # i18n key
-        href="/orders",
+        label="orders.menu.orders",     # i18n key, resolved client-side
+        url="/orders",
         icon="package",
-        required_permission="orders.view",
+        roles=["admin"],                # empty = all authenticated users
         order=20,
     ))
 ```
 
-`required_permission` filters the item from users without the permission. `order` is a stable sort key (lower = earlier).
+`roles` filters the item to users holding at least one of the listed roles (empty list = visible to all authenticated users); `requires_auth` (default `True`) hides it from anonymous visitors. `order` is a stable sort key (lower = earlier).
 
 Sections: `SIDEBAR`, `ADMIN_SIDEBAR`, `NAVBAR`, `USER_DROPDOWN`.
 
@@ -73,14 +73,17 @@ Declare feature flags with defaults. The admin can toggle them at `/settings/fea
 
 ```python
 def register_feature_flags(self, registry: FeatureFlagRegistry) -> None:
-    registry.add("orders.new_checkout", default=False)
+    registry.add(FeatureFlagDefinition(
+        name="orders.new_checkout",
+        default_enabled=False,
+    ))
 ```
 
 Query from code:
 
 ```python
 flags = request.app.state.sm.feature_flags
-if flags.is_enabled("orders.new_checkout", user=request.state.principal):
+if flags.is_enabled("orders.new_checkout", tenant_id=request.state.tenant_id):
     ...
 ```
 
@@ -97,21 +100,21 @@ async def _on_order_placed(self, event: OrderPlaced) -> None:
     ...
 ```
 
-Dispatch walks the event's MRO, so subscribing to a base class delivers subclass events. See [Events](/framework/events).
+Handlers are keyed by the exact event type and run concurrently on publish. See [Events](/framework/events).
 
 ## `register_health_checks(registry)`
 
-Register named async checks. They're surfaced at `/admin/health`:
+Register named async checks. They're surfaced at `/health/ready`:
 
 ```python
 def register_health_checks(self, registry: HealthRegistry) -> None:
-    registry.add("orders.db", self._check_db)
+    registry.add(HealthCheck(name="orders.db", check=self._check_db))
 
-async def _check_db(self) -> HealthStatus:
+async def _check_db(self) -> HealthCheckResult:
     ...
 ```
 
-Return `HealthStatus.ok()` or `HealthStatus.failing(detail=...)`. The health endpoint aggregates all checks and returns 503 if any critical check fails.
+Each check returns a `HealthCheckResult(status=HealthStatus.HEALTHY | DEGRADED | UNHEALTHY, detail=...)`. The `/health/ready` endpoint runs all checks concurrently and reports the worst status (a raising check counts as `UNHEALTHY`).
 
 ## `register_exception_handlers(app)`
 
@@ -146,29 +149,29 @@ Mount your API and Inertia view routers onto the two framework-provided routers.
 
 ```python
 def register_routes(
-    self, api: APIRouter, views: APIRouter
+    self, api_router: APIRouter, view_router: APIRouter
 ) -> None:
-    from orders.endpoints.api import router as api_router
-    from orders.endpoints.views import router as view_router
+    from orders.endpoints.api import router as api
+    from orders.endpoints.views import router as views
 
-    api.include_router(api_router, prefix="/api/orders")
-    views.include_router(view_router, prefix="/orders")
+    api_router.include_router(api)
+    view_router.include_router(views)
 ```
 
-- `api_router` is mounted at `/api` on the main app.
-- `view_router` is mounted at `/` on the main app.
+- `api_router` is pre-built with `prefix=ModuleMeta.route_prefix`.
+- `view_router` is pre-built with `prefix=ModuleMeta.view_prefix`.
 
-Prefixes in `ModuleMeta.route_prefix` / `view_prefix` are **documentation**; the framework does not auto-apply them. You specify the prefix in `include_router`.
+The framework **auto-applies** `ModuleMeta.route_prefix` / `view_prefix` — `create_app` constructs each router already prefixed (`APIRouter(prefix=module.meta.route_prefix)`), so your `include_router` calls usually pass no further prefix (add one only for a sub-grouping *inside* the module's own prefix).
 
 ## `on_startup()` / `on_shutdown()`
 
 Async lifespan hooks that run after all modules are registered.
 
 ```python
-async def on_startup(self) -> None:
+async def on_startup(self, app: FastAPI) -> None:
     await self._worker_pool.start()
 
-async def on_shutdown(self) -> None:
+async def on_shutdown(self, app: FastAPI) -> None:
     await self._worker_pool.stop()
 ```
 
@@ -198,14 +201,15 @@ class OrdersModule(ModuleBase):
     def register_menu_items(self, registry): ...
     def register_permissions(self, registry): ...
     def register_feature_flags(self, registry): ...
-    def register_event_handlers(self, bus): ...
+    def register_event_handlers(self, bus, app=None): ...
     def register_health_checks(self, registry): ...
+    def register_public_routes(self, registry): ...
     def register_exception_handlers(self, app): ...
     def register_middleware(self, app): ...
-    def register_routes(self, api, views): ...
+    def register_routes(self, api_router, view_router): ...
 
-    async def on_startup(self): ...
-    async def on_shutdown(self): ...
+    async def on_startup(self, app): ...
+    async def on_shutdown(self, app): ...
 ```
 
 If your module overrides zero hooks, diagnostic `SM007` (INFO) asks whether the module is still doing anything useful. Empty modules are typically deletable.
diff --git a/docs/framework/middleware.md b/docs/framework/middleware.md
index 8e69ca78..388b24dd 100644
--- a/docs/framework/middleware.md
+++ b/docs/framework/middleware.md
@@ -4,22 +4,25 @@ Starlette's `app.add_middleware(...)` is **LIFO**. The last middleware added is
 
 ## Installation order (inside `create_app`)
 
+The actual `add_middleware` call order (in `install_middleware`) is the
+**reverse** of execution order, because the first added wraps innermost:
+
 ```python
-# Added last → executed first (outermost wrapper)
-app.add_middleware(CorrelationIdMiddleware)
-app.add_middleware(RequestLoggingMiddleware)
-app.add_middleware(SecurityHeadersMiddleware)
-app.add_middleware(SessionMiddleware, secret_key=...)
+# Added first → executed last (closest to the app)
+app.add_middleware(InertiaLayoutDataMiddleware, ...)
+app.add_middleware(LocaleMiddleware, ...)
+
+if settings.multi_tenant:
+    app.add_middleware(TenantMiddleware, ...)
 
 for module in discovered_modules:
     module.register_middleware(app)   # each module may add 0+ middleware
 
-if settings.multi_tenant:
-    app.add_middleware(TenantMiddleware)
-
-app.add_middleware(LocaleMiddleware)
-app.add_middleware(InertiaLayoutDataMiddleware)
-# Added first → executed last (closest to the app)
+app.add_middleware(SessionMiddleware, secret_key=...)
+app.add_middleware(SecurityHeadersMiddleware, ...)
+app.add_middleware(RequestLoggingMiddleware)
+app.add_middleware(CorrelationIdMiddleware)
+# Added last → executed first (outermost wrapper)
 ```
 
 ## Execution order (per request)
@@ -88,7 +91,7 @@ Emits a structured log line per request with method, path, status, duration, and
 
 ### `SecurityHeadersMiddleware`
 
-Sets conservative defaults: `X-Content-Type-Options: nosniff`, `Referrer-Policy: strict-origin-when-cross-origin`, `X-Frame-Options: DENY`, plus CSP / HSTS in production. Override on a per-route basis with your own response headers.
+Sets conservative defaults: `X-Content-Type-Options: nosniff`, `Referrer-Policy: strict-origin-when-cross-origin`, `X-Frame-Options: SAMEORIGIN`, `X-XSS-Protection: 0` (the legacy auditor is disabled in favour of CSP), plus a default CSP and — outside development — HSTS. In development the CSP is widened for the Vite dev origin and HSTS is suppressed. Override on a per-route basis with your own response headers.
 
 ### `SessionMiddleware`
 
@@ -96,7 +99,7 @@ Starlette's built-in signed-cookie sessions. Cookie name is `session`; attribute
 
 ### `TenantMiddleware` *(opt-in)*
 
-Reads `SM_TENANT_HEADER` (default `X-Tenant-ID`) and sets `request.state.tenant_id`. The `MultiTenantMixin` auto-filters SELECTs and auto-populates INSERTs using this value.
+Resolves the tenant — first from the authenticated user's `tenant_id`, then (if the configured header is enabled, default name `X-Tenant-ID` via `SM_TENANT_HEADER`) from that request header — and sets both `request.state.tenant_id` and the `current_tenant_id` ContextVar. The `MultiTenantMixin` auto-filters SELECTs and auto-populates INSERTs using this value.
 
 ### `LocaleMiddleware`
 
diff --git a/docs/framework/overview.md b/docs/framework/overview.md
index e5548481..22df9b99 100644
--- a/docs/framework/overview.md
+++ b/docs/framework/overview.md
@@ -20,7 +20,7 @@ What actually happens when you run `uvicorn main:app`:
    `Settings`, `DatabaseState` (engines per provider), `EventBus`, `MenuRegistry`, `PermissionRegistry`, `FeatureFlagRegistry`, `HealthRegistry`, `I18nRegistry`. They are bundled into a frozen `Services` dataclass and attached to `app.state.sm`.
 3. **Discovery** — `discover_modules()` reads Python entry points under the `simple_module` group, imports each one, validates it's a `ModuleBase` subclass with a non-null `meta`, and topologically sorts by `ModuleMeta.depends_on`.
 4. **Lifecycle hooks run in sorted order**. For each module, in this order:
-   `register_settings` → `register_menu_items` → `register_permissions` → `register_feature_flags` → `register_event_handlers` → `register_health_checks` → `register_exception_handlers` → `register_middleware` → `register_routes(api_router, view_router)`.
+   `register_settings` → `register_menu_items` → `register_permissions` → `register_feature_flags` → `register_event_handlers` → `register_health_checks` → `register_public_routes` → `register_exception_handlers` → `register_middleware` → `register_routes(api_router, view_router)`.
 5. **Middleware is installed** — framework middleware first, then whatever modules registered. See [Middleware pipeline](/framework/middleware).
 6. **Routers mount** — `api_router` at `/api`, `view_router` at `/`. Each module's sub-routers were attached via `register_routes`.
 7. **Lifespan `on_startup`** — each module's async `on_startup` runs in dependency order. This is where background workers, warm caches, or remote-service health probes start.
@@ -43,10 +43,10 @@ The distinction exists so developer ergonomics aren't gated on fixing every warn
 
 ## The Services container
 
-Framework singletons live on `app.state.sm`, a frozen dataclass defined in `simple_module_hosting.services`:
+Framework singletons live on `app.state.sm`, a frozen dataclass defined in `simple_module_core.services`:
 
 ```python
-@dataclass(frozen=True)
+@dataclass(frozen=True, slots=True)
 class Services:
     settings: Settings
     db: DatabaseState
@@ -55,6 +55,7 @@ class Services:
     permissions: PermissionRegistry
     feature_flags: FeatureFlagRegistry
     health_registry: HealthRegistry
+    public_routes: PublicRouteRegistry
     i18n_registry: I18nRegistry
     inertia_config: InertiaConfig
     modules: tuple[ModuleBase, ...]
@@ -89,7 +90,7 @@ This is how the `auth.user` shared prop is built: framework middleware calls wha
 ## Next steps
 
 - [Discovery & entry points](/framework/discovery) — how modules are installed and found.
-- [Lifecycle hooks](/framework/lifecycle) — the 10 hooks in call order with examples.
+- [Lifecycle hooks](/framework/lifecycle) — the lifecycle hooks in call order with examples.
 - [Middleware pipeline](/framework/middleware) — execution order and how to slot your own in.
 - [Settings & app.state](/framework/settings) — framework vs. module state.
-- [Bundled modules](/modules/) — the eight first-party modules and what each one ships.
+- [Bundled modules](/modules/) — the ten first-party modules and what each one ships.
diff --git a/docs/framework/permissions.md b/docs/framework/permissions.md
index b31eea12..eb2fced2 100644
--- a/docs/framework/permissions.md
+++ b/docs/framework/permissions.md
@@ -49,7 +49,7 @@ async def create_order(...): ...
 async def export_orders(...): ...
 ```
 
-`RequiresPermission` raises `HTTPException(403)` if the current principal lacks the permission. Unauthenticated requests return 401 — the auth middleware runs earlier and attaches `request.state.principal`.
+`RequiresPermission` raises `HTTPException(403)` if the current user lacks the permission. Unauthenticated requests return 401 — `AuthMiddleware` runs earlier and attaches `request.state.user` (a `UserContext`) plus the resolved permission set on `request.state.resolved_permissions`.
 
 ## Roles
 
@@ -69,49 +69,49 @@ Host apps customize this by:
 
 The framework ships only `admin: ["*"]`. The wildcard grants every declared permission.
 
-## Principal resolution
+## User resolution
 
-For each request, middleware resolves the current **principal** — a normalized user snapshot with expanded permissions — onto `request.state.principal`:
+For each request, `AuthMiddleware` resolves the authenticated user onto `request.state.user` as a `UserContext` (from `auth.contracts.schemas`):
 
 ```python
 @dataclass
-class Principal:
-    user_id: int | None
-    email: str | None
-    roles: list[str]
-    permissions: set[str]
+class UserContext:
+    id: str
+    email: str
+    name: str
+    roles: list[str] = field(default_factory=list)
+    tenant_id: str | None = None
 ```
 
-The `users` module owns the extraction from the session cookie. The framework's `InertiaLayoutDataMiddleware` reads `request.state.principal` and serializes `auth.user`, `auth.isAuthenticated`, `auth.permissions` into the Inertia shared props.
+The active auth provider (the `users` or `keycloak` module) owns extraction from the session cookie / bearer token. `InertiaLayoutDataMiddleware` then expands roles into a permission set (cached on `request.state.resolved_permissions`) and serializes `auth.user`, `auth.isAuthenticated`, `auth.permissions` into the Inertia shared props. `UserContext` carries roles, not permissions — permissions are derived from the `PermissionRegistry.role_map`.
 
-## Permission shorthand for menus
+## Role shorthand for menus
 
-`MenuItem.required_permission` hides an item from users who don't have it. Evaluated in `InertiaLayoutDataMiddleware` *before* sending the menu to the client — the client never sees menu items it can't use.
+`MenuItem.roles` hides an item from users who hold none of the listed roles (an empty list = visible to all authenticated users); `requires_auth` (default `True`) hides it from anonymous visitors. Filtering happens in `MenuRegistry.get_for_user`, called by `InertiaLayoutDataMiddleware` *before* the menu reaches the client — so the client never sees menu items it can't use.
 
 ```python
 registry.add(MenuItem(
     section=MenuSection.SIDEBAR,
-    key="orders",
-    label_key="orders.menu.orders",
-    href="/orders",
-    required_permission="orders.view",
+    label="orders.menu.orders",
+    url="/orders",
+    roles=["admin"],
 ))
 ```
 
-If you need a conjunction of permissions, use a comma-separated string (`"a,b"` means both) or a dedicated `required_any_of: list[str]` — see `simple_module_core.menu`.
+Menu visibility is **role**-based (`MenuItem` has no `required_permission` field) — see `simple_module_core.menu`. Enforce the actual permission on the endpoint with `RequiresPermission`.
 
 ## Client-side checks
 
 The Inertia shared props include `auth.permissions`. Use them for UI affordances (hide/disable buttons), not for security:
 
 ```tsx
-import { useAuth } from "@simple-module-py/ui";
+import { usePermissions } from "@simple-module-py/ui/hooks/use-permissions";
 
 export default function OrdersToolbar() {
-  const { permissions } = useAuth();
+  const { can } = usePermissions();
   return (
     <div>
-      {permissions.has("orders.create") && (
+      {can("orders.create") && (
         <Button>Create order</Button>
       )}
     </div>
@@ -128,14 +128,15 @@ The `authenticated_client` fixture in `conftest.py` seeds an admin user (who has
 ```python
 @pytest.mark.asyncio
 async def test_create_requires_permission(client, db_session):
-    # Create a user without `orders.create`
-    from users.bootstrap import create_user
-    user = await create_user(db_session, email="u@e.com", password="x")
-    # Sign in via HTTP to get the session cookie
+    # Create a user without `orders.create` (e.g. via the users
+    # registration flow or by inserting a users.models.User row directly —
+    # users.bootstrap only ships create_admin).
+    ...
+    # Sign in via the local-auth API to get the session cookie.
     r = await client.post(
-        "/users/login", data={"email": "u@e.com", "password": "x"}
+        "/api/users/auth/login", data={"username": "u@e.com", "password": "x"}
     )
-    assert r.status_code in (200, 303)
+    assert r.status_code in (200, 204)
 
     r = await client.post("/api/orders", json={...})
     assert r.status_code == 403
@@ -146,4 +147,4 @@ async def test_create_requires_permission(client, db_session):
 - **Namespace with the module name.** `orders.create`, not `create_order`.
 - **Use `<module>.<verb>` form.** Nouns like `orders.admin` are fine for broad grants.
 - **Don't inline string checks.** `if "orders.create" in principal.permissions: ...` scattered through code is hard to audit. Use `RequiresPermission` or refactor into a dependency.
-- **Don't use roles in business logic.** Check permissions, not `principal.roles`. Roles are an admin concept; permissions are the enforcement boundary.
+- **Don't use roles in business logic.** Check permissions, not `user.roles`. Roles are an admin concept; permissions are the enforcement boundary.
diff --git a/docs/framework/principal-resolvers.md b/docs/framework/principal-resolvers.md
index ba380554..f97e519e 100644
--- a/docs/framework/principal-resolvers.md
+++ b/docs/framework/principal-resolvers.md
@@ -5,7 +5,7 @@ The `auth` module exposes an extension point — a list of async resolvers on
 additional credential sources alongside the built-in session cookie. This is
 the supported way to add Personal Access Tokens, API keys, JWT bearers, or
 any other request-scoped authentication scheme without forking
-`users.AuthMiddleware`.
+`auth.AuthMiddleware`.
 
 ## The contract
 
@@ -34,16 +34,19 @@ A resolver MUST:
 
 ## Resolution order
 
-`users.AuthMiddleware` consults credential sources in this order:
+`auth.AuthMiddleware` consults credential sources in this order:
 
-1. **Session cookie** — the existing fast/cached path. If the session
-   carries a valid `user_id` (and matching cached `user_ctx`), the user is
-   authenticated and the resolver chain is **not** consulted.
+1. **The active `AuthProvider`** — `provider.resolve_user(request)`, the
+   existing fast/cached path (session cookie for the `users` provider). If it
+   returns a `UserContext`, the user is authenticated and the resolver chain
+   is **not** consulted.
 2. **Registered resolvers**, in registration order. The first non-`None`
    return wins.
-3. **Unauthenticated** — for `/api/*` paths the middleware returns
-   `401 {"detail": "Not authenticated"}`; for view paths it 302-redirects to
-   `/users/login` and stashes the original URL in `session["next"]`.
+3. **Unauthenticated** — for `/api/*` paths (or any request the provider
+   reports as a bearer request) the middleware returns
+   `401 {"detail": "Not authenticated"}`; otherwise it 302-redirects to
+   `provider.get_login_url(request)` (the `users` provider's is `/users/login`)
+   and stashes the original URL in `session["next"]`.
 
 The chain runs on **every** request, including public paths (`/health`,
 `/openapi.json`, the login page itself). That lets a resolver attach
@@ -99,8 +102,10 @@ class ExampleModule(ModuleBase):
 ```
 
 `depends_on=["Auth", "Users"]` ensures `AuthModule.register_settings` has
-run (so `app.state.auth` exists) and `UsersModule.register_middleware` has
-installed `AuthMiddleware` (which calls the resolvers).
+run (so `app.state.auth` exists) and — since `AuthModule.register_middleware`
+installs `AuthMiddleware` (which calls the resolvers) — that the auth stack is
+wired before this module's `on_startup` appends its resolver. The `Users`
+dependency is for loading the user records the resolver looks up.
 
 ### Performance — caching the token lookup
 
diff --git a/docs/framework/public-routes.md b/docs/framework/public-routes.md
index a5692e4a..a1d3f3f6 100644
--- a/docs/framework/public-routes.md
+++ b/docs/framework/public-routes.md
@@ -68,8 +68,8 @@ to anonymous callers.
 
 For each request, `AuthMiddleware` treats the path as public if **any** of:
 
-1. **Framework defaults** — `/health`, `/static/`, `/api/docs`, `/openapi.json`,
-   `/i18n/`, the root `/`.
+1. **Framework defaults** — `/health`, `/static/`, `/api/docs`, `/api/redoc`,
+   `/openapi.json`, `/i18n/`, the root `/`.
 2. **`app.state.public_routes`** — the `PublicRouteRegistry` (module hooks +
    `SM_AUTH_PUBLIC_PATHS`). Method-aware.
 3. **`provider.get_public_paths()`** — the auth provider's own login / register
diff --git a/docs/framework/settings.md b/docs/framework/settings.md
index 1d4fdd5a..081df4b8 100644
--- a/docs/framework/settings.md
+++ b/docs/framework/settings.md
@@ -6,34 +6,34 @@ There are **three** separate settings surfaces in a running app. They serve diff
 |---|---|---|---|
 | **Framework env** (`Settings`) | `app.state.sm.settings` | No (read once at boot) | DB URL, secret key, log level, anything needed before the DB is open. |
 | **Module env** (`<Module>Env`) | `app.state.<module>.settings` | No | Module bootstrap knobs that must be resolved before DB-backed settings load. |
-| **DB-backed settings** | `sm_settings.settings` table, edited via `/settings/modules` | Yes | Everything else: SMTP creds, storage backends, feature toggles that operators tune. |
+| **DB-backed settings** | `settings_setting` table, edited via `/settings/modules` | Yes | Everything else: SMTP creds, storage backends, feature toggles that operators tune. |
 
 ## Framework settings
 
-Defined as a pydantic `BaseSettings` subclass in `simple_module_hosting.settings`:
+`Settings` (in `simple_module_hosting.settings`) combines `BootstrapSettings` (env-only, read before the DB is open) and `HostSettings`. The pre-DB knobs are a pydantic `BaseSettings` subclass:
 
 ```python
-class Settings(BaseSettings):
+class BootstrapSettings(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="SM_", env_file=".env", extra="ignore")
+
     database_url: str = "sqlite+aiosqlite:///./app.db"
     environment: str = "development"
     secret_key: str = "change-me-in-production"
     vite_dev_url: str = "http://localhost:5050"
     debug: bool = False
     log_level: str = "INFO"
-    log_format: str = "plain"
-    multi_tenant: bool = False
-    tenant_header: str = "X-Tenant-ID"
+    log_format: Literal["json", "text"] = "json"
     modules_enabled: list[str] | None = None
-
-    class Config:
-        env_prefix = "SM_"
+    auth_public_paths: list[str] = []
 ```
 
+The `SM_` prefix means every field is set via `SM_<FIELD>` (e.g. `SM_DATABASE_URL`, `SM_LOG_FORMAT`). `multi_tenant` / `tenant_header` and the other tunables live on the DB-backed `HostSettings` half.
+
 Construct once at boot, put on `app.state.sm.settings`, never mutated.
 
 ### Placeholder-secret check
 
-In production (`environment != "development"`), boot fails if `secret_key == "change-me-in-production"`. The check runs before middleware installation to avoid issuing signed cookies against a known-placeholder key.
+Outside the non-prod environments, boot fails if `secret_key == "change-me-in-production"`. A pydantic `model_validator(mode="after")` enforces this when `Settings()` is constructed — before any middleware can issue signed cookies against a known-placeholder key.
 
 ## Module settings
 
@@ -117,13 +117,14 @@ async def users_config(state: UsersStateDep):
 
 ## DB-backed settings
 
-After bootstrap, most configuration lives in the `sm_settings.settings` table and is edited via the admin UI at `/settings/modules`. Reads go through `SettingsService` which caches in-memory with invalidation on write:
+After bootstrap, most configuration lives in the `settings_setting` table and is edited via the admin UI at `/settings/modules`. The CRUD layer is `SettingService` (in `settings.service`); typed reads (with USER > TENANT > SYSTEM resolution and registered defaults) go through a `SettingsAccessor` that wraps it:
 
 ```python
-from settings.service import SettingsService
+from settings.service import SettingService
+from settings.contracts.accessor import SettingsAccessor
 
-service = SettingsService(session)
-max_size = await service.get_int("file_storage.max_upload_mb", default=10)
+accessor = SettingsAccessor(SettingService(session), registry)
+max_size = await accessor.get_int("file_storage.max_upload_mb", default=10)
 ```
 
 Values are keyed by `<namespace>.<key>`. Conventional namespace is the module name lowercased.
@@ -140,10 +141,10 @@ This reads the current environment, looks up keys the settings service knows abo
 
 ## Framework state (`app.state.sm`)
 
-Framework singletons — not settings, but long-lived services — live on `app.state.sm`, a frozen `Services` dataclass populated once at boot:
+Framework singletons — not settings, but long-lived services — live on `app.state.sm`, a frozen `Services` dataclass (defined in `simple_module_core.services`) populated once at boot:
 
 ```python
-@dataclass(frozen=True)
+@dataclass(frozen=True, slots=True)
 class Services:
     settings: Settings
     db: DatabaseState
@@ -152,6 +153,7 @@ class Services:
     permissions: PermissionRegistry
     feature_flags: FeatureFlagRegistry
     health_registry: HealthRegistry
+    public_routes: PublicRouteRegistry
     i18n_registry: I18nRegistry
     inertia_config: InertiaConfig
     modules: tuple[ModuleBase, ...]
diff --git a/docs/frontend/inertia.md b/docs/frontend/inertia.md
index 99f6d322..c66671b7 100644
--- a/docs/frontend/inertia.md
+++ b/docs/frontend/inertia.md
@@ -32,7 +32,7 @@ async def browse(inertia: InertiaDep, service: OrderServiceDep):
 
 Breakdown:
 
-- `InertiaDep` is a request-scoped dependency provided by fastapi-inertia. It's attached to `app.state.inertia_dependency` at boot.
+- `InertiaDep` (from `simple_module_hosting.inertia_deps`) is a request-scoped dependency that resolves the `Inertia` instance from `app.state.inertia_dependency` (configured at boot) and shares in `request.state.inertia_shared`.
 - The first argument to `render` is the **page key** — `"Orders/Browse"` maps to `modules/orders/orders/pages/Browse.tsx`. See [Pages & discovery](/frontend/pages).
 - `props` is a plain dict serialized to JSON. Use `model_dump(mode="json")` on SQLModel DTOs to get JSON-safe types (`Decimal → str`, `datetime → iso string`).
 
@@ -90,16 +90,19 @@ async def create(
 
 Inertia's client follows the redirect and renders the new page.
 
-## Flash messages
+## Toasts
 
-For "created successfully" toasts, use Starlette's session to flash a message:
+There is no `flash` shared prop. For "created successfully" toasts, fire `sonner`'s `toast` directly from the page's request callback:
 
-```python
-request.session["flash"] = {"type": "success", "message": "Order created"}
-return RedirectResponse("/orders", status_code=303)
+```tsx
+import { toast } from "sonner";
+
+router.post("/api/orders", data, {
+  onSuccess: () => toast.success("Order created"),
+});
 ```
 
-Then expose it in the shared props — `InertiaLayoutDataMiddleware` already reads `request.session.pop("flash", None)` and attaches it to `request.state.inertia_shared["flash"]`.
+Server-side validation errors arrive on the page's `errors` prop (fastapi-inertia's `use_flash_errors`, enabled in the Inertia config).
 
 ## What the shared props look like
 
@@ -108,7 +111,7 @@ Every Inertia response includes:
 ```ts
 {
   auth: {
-    user: { id, email, full_name, ... } | null,
+    user: { id, name, email, roles } | null,
     isAuthenticated: boolean,
     permissions: string[],
   },
@@ -120,31 +123,31 @@ Every Inertia response includes:
   },
   i18n: {
     locale: string,
-    bundle: Record<string, string>,   // flat key → value
+    supportedLocales: string[],
+    messages: Record<string, string> | null,   // flat key → value; null on unchanged-locale XHR partials
   },
-  flash: { type: string, message: string } | null,
 }
 ```
 
-Accessed from any page via `usePage().props.auth` etc., or via typed helpers from `@simple-module-py/ui` (`useAuth`, `useMenus`, `useT`).
+Accessed from any page via `usePage().props.auth` etc. (the exported `SharedProps` type from `@simple-module-py/ui` covers `auth` + `menus`); translations come from `useT()` in `@simple-module-py/i18n`. See [Shared props & layout](/frontend/shared-props).
 
 ## Frontend runtime setup
 
-`client_app/src/main.tsx` bootstraps Inertia:
+`host/client_app/main.tsx` imports `./styles.css` and `./app`; `app.tsx` bootstraps Inertia:
 
 ```tsx
 import { createInertiaApp } from "@inertiajs/react";
-import { resolvePage } from "./modules.generated";
+import { resolvePage } from "./pages";
 
 createInertiaApp({
-  resolve: resolvePage,
-  setup: ({ el, App, props }) => {
+  resolve: (name) => resolvePage(name),
+  setup({ el, App, props }) {
     createRoot(el).render(<App {...props} />);
   },
 });
 ```
 
-`resolvePage` is generated by `make gen-pages` from the module manifest. It maps a page key (e.g. `"Orders/Browse"`) to a dynamic import of the matching `.tsx` file.
+`resolvePage` lives in `host/client_app/pages.ts` (hand-written). It builds a page-key → loader map from `moduleGlobs` (the `import.meta.glob` calls in the generated `modules.generated.ts`) plus the host's own `./pages/**/*.tsx` glob, mapping a page key (e.g. `"Orders/Browse"`) to a dynamic import of the matching `.tsx` file.
 
 ## CSRF
 
diff --git a/docs/frontend/pages.md b/docs/frontend/pages.md
index 6f285a9d..2346e8fb 100644
--- a/docs/frontend/pages.md
+++ b/docs/frontend/pages.md
@@ -12,11 +12,11 @@ The server identifies a page by a **key**: `"<ModuleName>/<PageName>"`.
 | `modules/orders/orders/pages/Create.tsx` | `"Orders/Create"` |
 | `modules/orders/orders/pages/admin/Settings.tsx` | `"Orders/admin/Settings"` |
 | `modules/blog_posts/blog_posts/pages/Edit.tsx` | `"BlogPosts/Edit"` |
-| `client_app/pages/Landing.tsx` | `"Landing"` (host-level, no namespace) |
+| `host/client_app/pages/Landing.tsx` | `"Landing"` (host-level, no namespace) |
 
-- **`<ModuleName>`** is the **PascalCase** of the module's package directory: `blog_posts` → `BlogPosts`, `file_storage` → `FileStorage`.
+- **`<ModuleName>`** is the module's `ModuleMeta.name` — by convention the **PascalCase** of the module's package directory: `blog_posts` → `BlogPosts`, `file_storage` → `FileStorage`.
 - **`<PageName>`** is the path under `pages/` minus `.tsx`. Subdirectories become slashes: `admin/Settings.tsx` → `admin/Settings`.
-- **Host-level pages** live under `client_app/pages/` and use just the page name without a namespace prefix.
+- **Host-level pages** live under `host/client_app/pages/` and use just the page name without a namespace prefix.
 
 ## Rendering
 
@@ -28,7 +28,7 @@ return await inertia.render(
 )
 ```
 
-The key must match a generated entry in `modules.generated.ts`. Mismatches produce:
+The key must resolve against the page map built from `modules.generated.ts`. Mismatches produce:
 
 - **`SM003`** (warning) — the `.tsx` file exists, but no `inertia.render()` call in any module references it. The page is orphaned.
 - **`SM004`** (warning) — an `inertia.render("Orders/Unknown", ...)` call exists, but there's no matching `.tsx` file. You'll get a runtime error when a user hits that route.
@@ -37,33 +37,26 @@ Both fire at app boot.
 
 ## The generation pipeline
 
-`make gen-pages` (invoked automatically by `make dev` before starting Vite) runs `scripts/gen_pages.py`. It:
+`make gen-pages` (invoked automatically by `make dev` before starting Vite) runs `smpy host gen-pages --host-dir=host/client_app` (`simple_module_hosting.manifest.write_module_pages_manifest`). It:
 
 1. Discovers every installed module's page directory.
-2. Builds an object literal mapping page keys to dynamic imports.
-3. Writes three files to `client_app/`:
-   - `modules.generated.ts` — the `resolvePage` function used by Inertia.
-   - `modules.manifest.json` — metadata used by diagnostics.
-   - `modules.generated.css` — imports for any module-scoped CSS.
+2. Emits one `import.meta.glob` call per module, keyed by the module's `meta.name`.
+3. Writes three files to `host/client_app/`:
+   - `modules.generated.ts` — exports `moduleGlobs` (a `Record<ModuleName, Record<filePath, loader>>`).
+   - `modules.manifest.json` — name → absolute pages dir, used by Vite and diagnostics.
+   - `modules.generated.css` — `@source` entries for wheel-installed module pages.
 
-These files are **regenerated on every `make dev` run**. Never hand-edit them. Add them to `.gitignore` if they aren't already.
+These files are **regenerated on every `make dev` run** (only rewritten when content changes) and are **gitignored**. Never hand-edit them.
 
 ```ts
-// client_app/modules.generated.ts  (generated)
-export async function resolvePage(name: string) {
-  switch (name) {
-    case "Orders/Browse":
-      return (await import("../../modules/orders/orders/pages/Browse.tsx")).default;
-    case "Orders/Create":
-      return (await import("../../modules/orders/orders/pages/Create.tsx")).default;
-    // ...
-    default:
-      throw new Error(`Unknown page: ${name}`);
-  }
-}
+// host/client_app/modules.generated.ts  (generated)
+export const moduleGlobs: Record<string, Record<string, () => Promise<PageModule>>> = {
+  "Orders": import.meta.glob<PageModule>("../../modules/orders/orders/pages/**/*.tsx"),
+  // ...
+};
 ```
 
-Vite resolves these imports normally at build time and HMR-watches them in dev.
+`host/client_app/pages.ts` (hand-written) turns `moduleGlobs` plus the host's own `./pages/**/*.tsx` glob into a `{ "<ModuleName>/<PageName>": loader }` map and exports the `resolvePage(name)` used by Inertia. Vite resolves these imports normally at build time and HMR-watches them in dev.
 
 ## Writing a page
 
@@ -71,8 +64,8 @@ A minimal page:
 
 ```tsx
 // modules/orders/orders/pages/Browse.tsx
-import { useT } from "@simple-module-py/i18n-react";
-import { PageHeader } from "@simple-module-py/ui";
+import { useT } from "@simple-module-py/i18n";
+import { SectionTitle } from "@simple-module-py/ui/components/SectionTitle";
 import type { OrderOut } from "../contracts";
 
 interface BrowseProps {
@@ -83,7 +76,7 @@ export default function Browse({ orders }: BrowseProps) {
   const { t } = useT();
   return (
     <>
-      <PageHeader title={t("orders.browse.title")} />
+      <SectionTitle>{t("orders.browse.title")}</SectionTitle>
       <ul>
         {orders.map((o) => (
           <li key={o.id}>
@@ -98,7 +91,7 @@ export default function Browse({ orders }: BrowseProps) {
 
 - `export default` is **required** — Inertia's resolver expects a default export.
 - Props are passed from the server; type them explicitly.
-- Use `useT()` for i18n and `useAuth()` / `useMenus()` from `@simple-module-py/ui` for shared props.
+- Use `useT()` from `@simple-module-py/i18n` for translations and `usePage()` (with the `SharedProps` type from `@simple-module-py/ui`) for `auth` / `menus`.
 
 ## Subdirectories
 
@@ -141,17 +134,19 @@ The second form re-uses the layout instance across navigations — good for layo
 
 ## Shared components
 
-`packages/ui` is a shared shadcn-based component library. It's a proper npm workspace — import via its package name, not relative paths:
+`packages/ui` is a shared shadcn-based component library. It's a proper npm workspace — import via its package name, not relative paths. Module pages import shadcn primitives and layouts from their subpaths:
 
 ```tsx
 // ✅
-import { Button, DataTable, Input } from "@simple-module-py/ui";
+import { Button } from "@simple-module-py/ui/components/ui/button";
+import { StatCard } from "@simple-module-py/ui/components/StatCard";
+import { AuthenticatedLayout } from "@simple-module-py/ui/layouts/AuthenticatedLayout";
 
 // ❌
-import { Button } from "../../../../packages/ui/src/components/ui/Button";
+import { Button } from "../../../../packages/ui/src/components/ui/button";
 ```
 
-The Vite alias is set up so `@simple-module-py/ui` resolves at build time.
+The package's `exports` map and tsconfig `paths` resolve `@simple-module-py/ui/*` at build time.
 
 ## Module-scoped CSS
 
@@ -161,7 +156,7 @@ If your module needs its own CSS (beyond Tailwind classes), put it in `modules/<
 import "./Browse.css";
 ```
 
-`make gen-pages` also emits `modules.generated.css`, which imports any `<module>/styles.css` declared at the module level.
+`make gen-pages` also emits `modules.generated.css` with Tailwind `@source` entries for wheel-installed module pages (in-repo modules are already covered by the static `@source` glob in `host/client_app/styles.css`).
 
 ## Page-level TypeScript
 
@@ -169,12 +164,12 @@ Each module's `tsconfig.json` extends the host's; page files can import across m
 
 ## Testing pages
 
-React tests use Vitest + Testing Library, configured in `vitest.setup.ts`. A minimal page test:
+React tests use Vitest + Testing Library, configured in the repo-root `vitest.config.ts` + `vitest.setup.ts` and run via `npm test`. A minimal page test:
 
 ```tsx
-// modules/orders/orders/pages/__tests__/Browse.test.tsx
+// packages/ui/src/components/StatCard.test.tsx
 import { render, screen } from "@testing-library/react";
-import Browse from "../Browse";
+import Browse from "./Browse";
 
 it("renders orders", () => {
   render(<Browse orders={[{ id: 1, customer_email: "a@b.c", status: "pending" }]} />);
@@ -182,4 +177,4 @@ it("renders orders", () => {
 });
 ```
 
-For tests that hit shared props (`useT`, `useAuth`), wrap in a mock provider — see `packages/ui/src/test-utils.tsx`.
+The root `vitest.config.ts` only includes tests under `packages/**` and `host/client_app/**`, so place `.test.tsx` files there. For components that read shared props (`useT`, `usePage`), mock the source module with `vi.mock("@simple-module-py/i18n", ...)` / `vi.mock("@inertiajs/react", ...)` — see `packages/ui/src/components/LocaleSwitcher.test.tsx`.
diff --git a/docs/frontend/shared-props.md b/docs/frontend/shared-props.md
index 9da8dc41..ad606a12 100644
--- a/docs/frontend/shared-props.md
+++ b/docs/frontend/shared-props.md
@@ -5,9 +5,10 @@ Every Inertia response carries a set of shared props attached by `InertiaLayoutD
 ## The contract
 
 ```ts
+// The exported SharedProps type (packages/ui/src/types.ts) covers auth + menus:
 interface SharedProps {
   auth: {
-    user: UserSummary | null;
+    user: { name: string; email: string; roles: string[] } | null;
     isAuthenticated: boolean;
     permissions: string[];
   };
@@ -17,11 +18,13 @@ interface SharedProps {
     navbar: MenuItem[];
     userDropdown: MenuItem[];
   };
-  i18n: {
-    locale: string;
-    bundle: Record<string, string>;
-  };
-  flash: { type: "success" | "error" | "info"; message: string } | null;
+}
+
+// Every Inertia response also carries an `i18n` block (read via usePage().props.i18n):
+interface I18nSharedProps {
+  locale: string;
+  supportedLocales: string[];
+  messages: Record<string, string> | null;   // null on Inertia XHR partials when the locale is unchanged
 }
 ```
 
@@ -29,64 +32,51 @@ interface SharedProps {
 
 `InertiaLayoutDataMiddleware` runs **last** in the middleware pipeline (closest to the app). For every outgoing Inertia response, it reads:
 
-- `request.state.principal` (set by the users module's auth middleware) and the registered `principal_serializer` to build `auth.user`.
-- `app.state.sm.menu_registry`, filtered by the current principal's permissions, to build `menus`.
+- `request.state.user` (set by the auth middleware) and the registered `app.state.principal_serializer` to build `auth.user`. The user's roles drive `auth.permissions`.
+- `menu_registry.get_for_user(...)`, filtered by the user's auth state and roles, to build `menus`.
 - `request.state.locale` + `app.state.sm.i18n_registry` to build `i18n`.
-- `request.session.pop("flash", None)` to build `flash`.
 
-Then it merges those into the Inertia payload under the "shared" slot.
+Then it stores the result on `request.state.inertia_shared`, which `get_inertia` (`simple_module_hosting.inertia_deps`) shares into the Inertia payload.
 
 ## Accessing from a page
 
-### Typed helpers
-
-Prefer the helpers from `@simple-module-py/ui`:
+Read `auth` / `menus` via Inertia's `usePage` and the exported `SharedProps` type; use `useT` from `@simple-module-py/i18n` for translations:
 
 ```tsx
-import { useAuth, useMenus, useT } from "@simple-module-py/ui";
+import { usePage } from "@inertiajs/react";
+import { useT } from "@simple-module-py/i18n";
+import type { SharedProps } from "@simple-module-py/ui";
 
 export default function Browse() {
-  const { user, permissions } = useAuth();
-  const { sidebar } = useMenus();
-  const { t, locale } = useT();
-  ...
+  const { auth, menus } = usePage<{ props: SharedProps }>().props as unknown as SharedProps;
+  const { t } = useT();
+  // auth.user, auth.permissions, menus.sidebar, ...
 }
 ```
 
-### Raw
-
-For cases where a helper doesn't cover your need, use Inertia's `usePage`:
-
-```tsx
-import { usePage } from "@inertiajs/react";
-import type { SharedProps } from "@simple-module-py/ui";
-
-const { props } = usePage<SharedProps>();
-console.log(props.auth.user, props.i18n.locale);
-```
+The layouts in `@simple-module-py/ui` (`SidebarLayout`, `PublicLayout`, …) read these props for you, so most pages don't touch `usePage` directly.
 
 ## `auth.user` — the principal serializer
 
-The framework doesn't know the shape of your `User`. A module (typically `users`) registers a `principal_serializer: Callable[[User], dict]` during `register_settings`:
+The framework doesn't know the shape of your `User`. A module (the `auth` module) assigns a serializer to `app.state.principal_serializer` during `register_settings`:
 
 ```python
-# modules/users/users/module.py
-class UsersModule(ModuleBase):
-    def register_settings(self, app: FastAPI) -> None:
-        app.state.sm.inertia_config.register_principal_serializer(
-            serialize_user
-        )
-
-def serialize_user(user: User) -> dict:
+# modules/auth/auth/module.py
+def _serialize_principal(user: UserContext) -> dict:
     return {
         "id": user.id,
+        "name": user.name,
         "email": user.email,
-        "full_name": user.full_name,
-        "roles": [r.name for r in user.roles],
+        "roles": user.roles,
     }
+
+class AuthModule(ModuleBase):
+    def register_settings(self, app: FastAPI) -> None:
+        app.state.auth = AuthState()
+        app.state.principal_serializer = _serialize_principal
 ```
 
-Without a registered serializer, `auth.user` is `None` even when a user is authenticated. This is intentional — the framework has no opinion on what a "user" is. If you replace the users module with your own auth, register your own serializer.
+Without a registered serializer, `auth.user` is `None` even when a user is authenticated. This is intentional — the framework has no opinion on what a "user" is. If you replace the auth module with your own, register your own serializer on `app.state.principal_serializer`.
 
 ## Menus
 
@@ -95,28 +85,29 @@ Populated from the `MenuRegistry`. Each module adds items during `register_menu_
 ```python
 registry.add(MenuItem(
     section=MenuSection.SIDEBAR,
-    key="orders",
-    label_key="orders.menu.orders",
-    href="/orders",
+    label="Orders",
+    url="/orders",
     icon="package",
-    required_permission="orders.view",
+    requires_auth=True,
+    roles=["admin"],   # empty list = visible to all authenticated users
     order=20,
 ))
 ```
 
-`InertiaLayoutDataMiddleware` filters by `required_permission` before sending — users who lack it never see the item.
+`menu_registry.get_for_user(is_authenticated=..., roles=...)` filters by `requires_auth` and `roles` before sending — users without a matching role never see the item.
 
-Render in a layout:
+Render in a layout via `usePage` and the `SharedProps` type:
 
 ```tsx
-import { useMenus } from "@simple-module-py/ui";
+import { usePage } from "@inertiajs/react";
+import type { MenuItem, SharedProps } from "@simple-module-py/ui";
 
 export function Sidebar() {
-  const { sidebar } = useMenus();
+  const { menus } = usePage<{ props: SharedProps }>().props as unknown as SharedProps;
   return (
     <nav>
-      {sidebar.map((item) => (
-        <a key={item.key} href={item.href}>
+      {menus.sidebar.map((item: MenuItem) => (
+        <a key={item.url} href={item.url}>
           {item.label}
         </a>
       ))}
@@ -125,49 +116,36 @@ export function Sidebar() {
 }
 ```
 
-Labels are **pre-translated**. The middleware runs through `I18nRegistry` before serializing, so the client just renders `item.label`.
+Labels are passed through as `item.label` — the module supplies the display string when it registers the item.
 
-## `flash` — flash messages
+## Toasts
 
-Flash a message server-side with Starlette's session:
-
-```python
-@router.post("")
-async def create(...):
-    ...
-    request.session["flash"] = {"type": "success", "message": "Order created"}
-    return RedirectResponse("/orders", status_code=303)
-```
-
-`InertiaLayoutDataMiddleware` pops and forwards it. Consume in a toast component:
+There is no `flash` shared prop. Pages fire toasts directly from their own request callbacks using `sonner`:
 
 ```tsx
-import { useFlash } from "@simple-module-py/ui";
-import { useEffect } from "react";
 import { toast } from "sonner";
 
-export function FlashToaster() {
-  const flash = useFlash();
-  useEffect(() => {
-    if (flash) toast[flash.type](flash.message);
-  }, [flash]);
-  return null;
-}
+router.post("/api/orders", data, {
+  onSuccess: () => toast.success("Order created"),
+  onError: () => toast.error("Failed to create order"),
+});
 ```
 
-Shows once per request, then gone.
+For server-driven error messages, the Inertia config enables fastapi-inertia's `use_flash_errors`, which surfaces validation errors on the page's `errors` prop.
 
-## `i18n` — the active bundle
+## `i18n` — the active messages
 
-`useT` reads the bundle and exposes `t(key, params?)`:
+`useT` (from `@simple-module-py/i18n`, a re-export of react-i18next's `useTranslation`) exposes `t(key, params?)`:
 
 ```tsx
-const { t, locale } = useT();
+import { useT } from "@simple-module-py/i18n";
+
+const { t } = useT();
 t("orders.browse.title");
 t("orders.items", { count: orders.length });   // pluralization
 ```
 
-The bundle is the **resolved locale's** translations merged across all modules. Switching the locale (via `<LocaleSwitcher />` or a direct POST to `/i18n/set-locale`) triggers a full-page navigation so the bundle is re-fetched.
+The `i18n.messages` block is the **resolved locale's** translations merged across all modules. Switching the locale (via `<LocaleSwitcher />`, which POSTs to `/i18n/set-locale`) triggers a full-page navigation so the messages are re-fetched. The active locale and supported locales are on `usePage().props.i18n` (`locale`, `supportedLocales`).
 
 ## Extending shared props
 
@@ -177,7 +155,7 @@ If your module needs to inject a new shared prop (e.g. feature flags), do **not*
 class FeatureFlagsSharedPropsMiddleware(BaseHTTPMiddleware):
     async def dispatch(self, request, call_next):
         flags = request.app.state.sm.feature_flags.evaluate_all(
-            principal=getattr(request.state, "principal", None)
+            principal=getattr(request.state, "user", None)
         )
         if not hasattr(request.state, "inertia_shared"):
             request.state.inertia_shared = {}
diff --git a/docs/guide/configuration.md b/docs/guide/configuration.md
index fb7c9025..07aedb71 100644
--- a/docs/guide/configuration.md
+++ b/docs/guide/configuration.md
@@ -7,9 +7,9 @@ Runtime configuration has **two** sources, in order of precedence:
 
 Most deployments only need `SM_DATABASE_URL` and `SM_SECRET_KEY` in the environment — everything else is configurable from the admin UI.
 
-## Framework env vars
+## Framework env vars (bootstrap)
 
-Prefix is always `SM_`. These are parsed by `simple_module_hosting.settings.Settings` (pydantic) at startup.
+Prefix is always `SM_`. These are the pre-DB knobs read by `simple_module_hosting.bootstrap_settings.BootstrapSettings` (pydantic) at startup — they're needed to open the DB, sign cookies, or configure the process, so they can't live in the DB-backed store.
 
 | Variable | Default | Notes |
 |---|---|---|
@@ -19,10 +19,11 @@ Prefix is always `SM_`. These are parsed by `simple_module_hosting.settings.Sett
 | `SM_VITE_DEV_URL` | `http://localhost:5050` | Dev only — where the Vite HMR client connects. |
 | `SM_DEBUG` | `false` | Enables debug mode (shows tracebacks in HTTP responses). |
 | `SM_LOG_LEVEL` | `INFO` | `DEBUG`/`INFO`/`WARNING`/`ERROR` |
-| `SM_LOG_FORMAT` | `plain` | `plain` for dev, `json` for structured logs in prod. |
-| `SM_MULTI_TENANT` | `false` | Enables `TenantMiddleware` + `MultiTenantMixin` auto-filter. |
-| `SM_TENANT_HEADER` | `X-Tenant-ID` | HTTP header that identifies the current tenant. |
+| `SM_LOG_FORMAT` | `json` | `json` (structured) or `text`. |
 | `SM_MODULES_ENABLED` | unset (all enabled) | Comma-separated allow-list to disable modules without uninstalling them. |
+| `SM_AUTH_PUBLIC_PATHS` | `[]` | JSON array of anonymous-access path prefixes — a host-level escape hatch. Modules should prefer the `register_public_routes` hook. |
+
+Multi-tenancy (`multi_tenant`, `tenant_header`) and i18n (`i18n_default_locale`, `i18n_supported_locales`, `i18n_cookie_name`) are **DB-backed host settings** now, not env vars — edit them under `host` at `/settings/modules`. (`smpy new --tenancy` still writes `SM_MULTI_TENANT=true` into `.env.example` as a scaffold convenience, and tests can override these.)
 
 ## Database bootstrap knobs
 
@@ -30,45 +31,42 @@ Only change if you know what you're doing — these must be set *before* the DB
 
 | Variable | Default | Notes |
 |---|---|---|
-| `SM_DB_POOL_SIZE` | `5` | SQLAlchemy `pool_size` |
-| `SM_DB_MAX_OVERFLOW` | `10` | SQLAlchemy `max_overflow` |
+| `SM_DB_POOL_SIZE` | `10` | SQLAlchemy `pool_size` |
+| `SM_DB_MAX_OVERFLOW` | `20` | SQLAlchemy `max_overflow` |
 | `SM_DB_POOL_PRE_PING` | `true` | Test connections before use |
 | `SM_DB_POOL_RECYCLE` | `1800` | Recycle connections after N seconds |
 
 ## Internationalization
 
-| Variable | Default | Notes |
+These are **DB-backed host settings** (under `host` in `/settings/modules`), not env vars.
+
+| Setting | Default | Notes |
 |---|---|---|
-| `SM_I18N_DEFAULT_LOCALE` | `en` | Must be in `SM_I18N_SUPPORTED_LOCALES`. |
-| `SM_I18N_SUPPORTED_LOCALES` | `en` | Comma-separated, e.g. `en,es,de`. |
-| `SM_I18N_COOKIE_NAME` | `locale` | Cookie that stores the user's selected locale. |
+| `i18n_default_locale` | `en` | Must be in `i18n_supported_locales`. |
+| `i18n_supported_locales` | `["en"]` | List of supported locales, e.g. `["en", "es", "de"]`. |
+| `i18n_cookie_name` | `locale` | Cookie that stores the user's selected locale. |
 
 ## Users module
 
-Prefix `SM_USERS_*`. These live in the env for bootstrap; everything else moved to the DB-backed settings store.
+Only the first-boot **bootstrap seed** is read from the env (prefix `SM_USERS_*`). Signup policy, mailer, SMTP creds, and base URL all moved to the DB-backed settings store — edit them under `users` at `/settings/modules`.
 
 | Variable | Default | Notes |
 |---|---|---|
 | `SM_USERS_BOOTSTRAP_EMAIL` | unset | Auto-creates an admin if set **and** `users_user` is empty. |
 | `SM_USERS_BOOTSTRAP_PASSWORD` | unset | Paired with the email above. |
-| `SM_USERS_ALLOW_SIGNUP` | `false` | If `true`, `/users/register` is public. |
-| `SM_USERS_MAILER` | `console` | `console` (logs invite link to stdout) or `smtp`. |
-| `SM_USERS_BASE_URL` | derived | The public URL used to build invite links. |
-| `SM_USERS_SMTP_HOST` | — | Only when `SM_USERS_MAILER=smtp`. |
-| `SM_USERS_SMTP_PORT` | `587` | |
-| `SM_USERS_SMTP_USERNAME` | — | |
-| `SM_USERS_SMTP_PASSWORD` | — | |
-| `SM_USERS_SMTP_FROM` | — | |
-| `SM_USERS_SMTP_TLS` | `true` | |
+| `SM_USERS_BOOTSTRAP_USER_EMAIL` | unset | Optional second, non-admin seed user. |
+| `SM_USERS_BOOTSTRAP_USER_PASSWORD` | unset | Paired with the user email above. |
+
+DB-backed users settings (defaults): `allow_signup=false`, `mailer=console` (or `smtp`), `base_url=http://localhost:8000`, and the `smtp_*` fields (`smtp_port=587`, `smtp_from=no-reply@localhost`, `smtp_tls=true`).
 
 ## Background tasks (Celery)
 
-Prefix `SM_BG_TASKS_*`. The defaults in `docker-compose.yml` already set these so Celery can reach the in-container `redis` service before DB-backed settings are loaded.
+The broker/result settings are DB-backed (under `background_tasks` in `/settings/modules`) with the defaults below. The generated `docker-compose.yml` sets `SM_BG_TASKS_BROKER_URL` / `SM_BG_TASKS_RESULT_BACKEND` on the `worker` and `beat` containers so they reach the in-container `redis` service.
 
-| Variable | Default | Notes |
+| Setting | Default | Notes |
 |---|---|---|
-| `SM_BG_TASKS_BROKER_URL` | `redis://localhost:6379/0` | Celery broker. |
-| `SM_BG_TASKS_RESULT_BACKEND` | `redis://localhost:6379/1` | Celery result backend. |
+| `broker_url` | `redis://localhost:6379/0` | Celery broker. |
+| `result_backend` | `redis://localhost:6379/1` | Celery result backend. |
 
 ## DB-backed settings
 
diff --git a/docs/guide/first-module.md b/docs/guide/first-module.md
index f06a19da..990a0d9a 100644
--- a/docs/guide/first-module.md
+++ b/docs/guide/first-module.md
@@ -70,10 +70,10 @@ DTOs are plain `SQLModel` subclasses — **not** `BaseModel` and **not** `table=
 ## 4. Generate a migration
 
 ```bash
-uv run alembic revision --autogenerate -m "add orders tables"
+make migration msg="add orders tables"
 ```
 
-Open `migrations/versions/XXXX_add_orders_tables.py` and eyeball it:
+Open `host/migrations/versions/XXXX_add_orders_tables.py` and eyeball it (`make migration` runs Alembic from the host dir):
 
 - It should create the `orders_order` table.
 - Add `branch_labels = ("orders",)` to the revision so you can later `alembic downgrade orders@base` to roll the module back to empty without touching other modules.
@@ -202,32 +202,50 @@ async def create_order(
     return await service.create(data)
 ```
 
-`RequiresPermission` checks `request.state.principal.permissions` and returns 403 if the permission isn't granted.
+`RequiresPermission` returns 401 if the request is unauthenticated and 403 if the resolved permissions (`request.state.resolved_permissions`, populated from the user's roles) don't include the required permission. A wildcard grant short-circuits the check.
 
 ## 8. Build the React page
 
 `pages/Browse.tsx` was scaffolded — extend it:
 
 ```tsx
-import { useT } from "@simple-module-py/i18n-react";
-import { DataTable, PageHeader } from "@simple-module-py/ui";
+import { useT } from "@simple-module-py/i18n";
+import { PageShell } from "@simple-module-py/ui/components/PageShell";
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from "@simple-module-py/ui/components/ui/table";
 import type { OrderOut } from "../contracts";
 
 export default function Browse({ orders }: { orders: OrderOut[] }) {
   const { t } = useT();
   return (
-    <>
-      <PageHeader title={t("orders.browse.title")} />
-      <DataTable
-        data={orders}
-        columns={[
-          { key: "id", header: "#" },
-          { key: "customer_email", header: t("orders.fields.customer") },
-          { key: "total", header: t("orders.fields.total") },
-          { key: "status", header: t("orders.fields.status") },
-        ]}
-      />
-    </>
+    <PageShell title={t("orders.browse.title")}>
+      <Table>
+        <TableHeader>
+          <TableRow>
+            <TableHead>#</TableHead>
+            <TableHead>{t("orders.fields.customer")}</TableHead>
+            <TableHead>{t("orders.fields.total")}</TableHead>
+            <TableHead>{t("orders.fields.status")}</TableHead>
+          </TableRow>
+        </TableHeader>
+        <TableBody>
+          {orders.map((order) => (
+            <TableRow key={order.id}>
+              <TableCell>{order.id}</TableCell>
+              <TableCell>{order.customer_email}</TableCell>
+              <TableCell>{order.total}</TableCell>
+              <TableCell>{order.status}</TableCell>
+            </TableRow>
+          ))}
+        </TableBody>
+      </Table>
+    </PageShell>
   );
 }
 ```
diff --git a/docs/guide/installation.md b/docs/guide/installation.md
index 9ef225a6..c99e628f 100644
--- a/docs/guide/installation.md
+++ b/docs/guide/installation.md
@@ -56,7 +56,7 @@ smpy new myapp --preset standard --with background_tasks,file_storage
 | `standard` (default) | `minimal` + `dashboard`, `permissions` |
 | `full` | `standard` + `settings`, `feature_flags`, `file_storage`, `background_tasks` |
 
-`simple_module_settings` is also installed as a baseline dependency of every scaffolded host (regardless of preset), so the Settings admin UI is available even in `minimal`. Dependencies between modules are resolved automatically — e.g. `users` always pulls in `auth`.
+Dependencies between modules are resolved automatically — e.g. `users` always pulls in `auth`, and `file_storage` pulls in `settings`. The `settings` module ships only in the `full` preset (or when added explicitly with `--with settings`).
 
 After scaffolding, `smpy new` runs `uv sync`, `npm install`, and `alembic upgrade head` for you (skip with `--no-install` if you'd rather drive that yourself).
 
@@ -82,20 +82,20 @@ Hit `http://localhost:8000`. You should see the landing page.
 SM_DATABASE_URL=sqlite+aiosqlite:///./app.db
 ```
 
-For Postgres:
+For Postgres, scaffold with `--db postgres` (or pick Postgres in the wizard) and `smpy new` writes a matching `SM_DATABASE_URL`:
 
 ```bash
 SM_DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/myapp
 ```
 
-The scaffolded `docker-compose.yml` brings up a `postgres` container on `:5432` (and a `redis` container on `:6379` when you include `background_tasks`):
+A `docker-compose.yml` is only generated when you include the `background_tasks` module; it brings up `postgres` (db `simple_module`, user `sm`/`sm`) on `:5432`, `redis` on `:6379`, and the `host`/`worker`/`beat` services:
 
 ```bash
 docker compose up -d postgres
 make migrate
 ```
 
-See [Configuration](/guide/configuration) for the full list of env vars.
+Without `background_tasks`, bring your own Postgres (or stay on the default SQLite). See [Configuration](/guide/configuration) for the full list of env vars.
 
 ## Create the first admin
 
@@ -121,7 +121,7 @@ Then `make migrate && make dev`.
 smpy create-module orders --dest modules/orders
 ```
 
-That generates `modules/orders/` with the full layout (model, contracts, service, endpoints, pages, tests, locales, `pyproject.toml` entry point). Add the package to your app's dependencies and re-sync:
+That generates a publishable module package at `modules/orders/` with the starter layout — `module.py` (its `ModuleBase` subclass + entry point), `services.py`, `settings.py`, a REST `endpoints/api.py`, an empty `pages/` dir, tests, and `pyproject.toml`/`package.json`/`tsconfig.json`. Flesh out models, contracts, views, and pages as your domain needs them. Add the package to your app's dependencies and re-sync:
 
 ```bash
 uv add ./modules/orders
@@ -142,7 +142,7 @@ Pass `--dry-run` first to preview the diff.
 
 ## Troubleshooting
 
-**`sm: command not found`** after `uv tool install`.
+**`smpy: command not found`** after `uv tool install`.
 Run `uv tool update-shell` (or restart your shell) so the tool's bin dir is on PATH.
 
 **Port already in use.**
diff --git a/docs/guide/introduction.md b/docs/guide/introduction.md
index 6bd46e88..5ba6e424 100644
--- a/docs/guide/introduction.md
+++ b/docs/guide/introduction.md
@@ -14,7 +14,7 @@ You get the distribution benefits of microservices — teams can own a module, s
 | Migrations | Alembic |
 | Frontend bridge | Inertia.js |
 | Frontend | React 19 + Tailwind CSS 4 + Vite |
-| Auth | fastapi-users (local email+password, cookie sessions) |
+| Auth | Pluggable auth providers — local email+password (cookie sessions) or Keycloak OIDC, with a principal-resolver chain (session or bearer token) |
 | Tooling | uv (Python), npm (JS), Ruff, ty, Biome, pytest, Playwright |
 
 ## When to reach for this
diff --git a/docs/guide/project-structure.md b/docs/guide/project-structure.md
index 79878c1f..3f2b523f 100644
--- a/docs/guide/project-structure.md
+++ b/docs/guide/project-structure.md
@@ -1,39 +1,41 @@
 # Project structure
 
-`smpy new myapp` lays down a focused tree. The host owns the runnable app; modules live as packages under `modules/`; everything else is configuration.
+`smpy new myapp` lays down a uv + npm **workspace** by default. The workspace root holds shared config; the runnable app lives under `host/`; your own modules live as workspace members under `modules/` (seeded with a sample `hello` module).
 
 ```text
 myapp/
-├── main.py                    # FastAPI entry point — create_app + lifespan
-├── pyproject.toml             # your app's deps (uv-managed)
-├── alembic.ini                # Alembic config — points at migrations/
+├── pyproject.toml             # uv workspace root (members: host, modules/*) — not itself installed
+├── package.json               # npm workspace root (host/client_app, modules/*)
 ├── .env.example               # default env vars; copy to .env
-├── docker-compose.yml         # Postgres + Redis for local dev
-├── Makefile                   # thin wrapper: dev / install / migrate / build / gen-pages
+├── Makefile                   # thin wrapper: install / dev / migrate / build / gen-pages
+├── README.md
 │
-├── client_app/                # Vite + React root
-│   ├── main.tsx               # bootstrap
-│   ├── pages/                 # host-level Inertia pages (Landing, NotFound)
-│   ├── modules.generated.ts   # auto-generated page map — DO NOT EDIT
-│   ├── modules.manifest.json  # auto-generated manifest — DO NOT EDIT
-│   ├── modules.generated.css  # auto-generated module CSS — DO NOT EDIT
-│   ├── package.json
-│   ├── tsconfig.json
-│   └── vite.config.ts
+├── host/                      # the runnable application
+│   ├── main.py                # FastAPI entry point — create_app + lifespan
+│   ├── routes.py
+│   ├── pyproject.toml          # host deps (uv-managed): hosting + selected modules
+│   ├── alembic.ini             # Alembic config — points at migrations/
+│   ├── Makefile
+│   ├── client_app/             # Vite + React root
+│   │   ├── main.tsx            # bootstrap
+│   │   ├── app.tsx, pages.ts
+│   │   ├── pages/              # host-level Inertia pages (Landing, Error)
+│   │   ├── modules.generated.ts   # auto-generated page map — DO NOT EDIT
+│   │   ├── modules.manifest.json  # auto-generated manifest — DO NOT EDIT
+│   │   ├── modules.generated.css  # auto-generated module CSS — DO NOT EDIT
+│   │   ├── package.json
+│   │   ├── tsconfig.json
+│   │   └── vite.config.ts
+│   └── migrations/             # Alembic migrations for ALL modules
+│       ├── env.py              # calls build_module_metadata() to union every module's MetaData
+│       └── versions/
 │
-├── migrations/                # Alembic migrations for ALL modules
-│   ├── env.py                 # calls build_module_metadata() to union every module's MetaData
-│   └── versions/
-│
-├── modules/                   # your custom modules go here (smpy create-module --dest modules/<name>)
-│   └── orders/                # example — generated by smpy create-module orders
-│       └── … (see "Anatomy of a module" below)
-│
-└── tests/                     # your app-level tests
-    └── test_smoke.py
+└── modules/                    # your workspace modules (smpy create-module --dest modules/<name>)
+    └── hello/                  # sample module scaffolded by smpy new
+        └── … (see "Anatomy of a module" below)
 ```
 
-`smpy new --flat` skips the `modules/` directory entirely, for the case where the app only consumes published modules and never authors its own. `smpy new --preset minimal` ships fewer pre-installed modules.
+`smpy new --flat` skips the workspace wrapper and the sample `hello` module, emitting a single-host layout (`main.py`, `client_app/`, `migrations/` at the top level) — use it when the app only consumes published modules and never authors its own. `smpy new --preset minimal` ships fewer pre-installed modules. A `docker-compose.yml` is added only when the `background_tasks` module is included.
 
 ## Bundled modules
 
@@ -89,17 +91,17 @@ See the [module authoring guide](/module-authoring) for the full contract.
 
 | File | Generated by | When |
 |---|---|---|
-| `client_app/modules.generated.ts` | `make gen-pages` (auto via `make dev`) | Every time you add/remove a module page |
-| `client_app/modules.manifest.json` | `make gen-pages` | Same |
-| `client_app/modules.generated.css` | `make gen-pages` | Same |
-| `migrations/versions/XXXX_*.py` | `uv run alembic revision --autogenerate -m "…"` | When you add/change SQLModel tables |
+| `host/client_app/modules.generated.ts` | `make gen-pages` (auto via `make dev`) | Every time you add/remove a module page |
+| `host/client_app/modules.manifest.json` | `make gen-pages` | Same |
+| `host/client_app/modules.generated.css` | `make gen-pages` | Same |
+| `host/migrations/versions/XXXX_*.py` | `make migration msg="…"` | When you add/change SQLModel tables |
 | `modules/<name>/**` | `smpy create-module <name> --dest modules/<name>` | Scaffolding a new module |
 
 Never hand-edit the `.generated.*` files — they are overwritten on the next `make gen-pages` run.
 
 ## Where things intentionally *don't* live
 
-- **No per-module `migrations/` folder.** All migrations live in `migrations/versions/`. Autogenerate discovers every installed module's metadata via `build_module_metadata()` in `migrations/env.py`. Each module's first migration sets a `branch_labels` marker to enable `alembic downgrade <module>@base`.
+- **No per-module `migrations/` folder.** All migrations live in `host/migrations/versions/`. Autogenerate discovers every installed module's metadata via `build_module_metadata()` in `host/migrations/env.py`. Each module's first migration sets a `branch_labels` marker to enable `alembic downgrade <module>@base`.
 - **No host-level `api/` folder.** REST endpoints are attached by each module via `register_routes(api_router, view_router)`. `/api/*` is the union of every module's API router.
 - **No `schemas/` top-level folder.** DTOs live inside the owning module's `contracts/` so other modules import them by name — the reverse of a monolith's "shared schemas" directory.
 
diff --git a/docs/guide/quickstart.md b/docs/guide/quickstart.md
index 9deae01f..f504d3c9 100644
--- a/docs/guide/quickstart.md
+++ b/docs/guide/quickstart.md
@@ -17,7 +17,7 @@ smpy new myapp --yes
 cd myapp
 ```
 
-`--yes` accepts the defaults (SQLite, no multi-tenancy, the `standard` preset: `auth`, `users`, `dashboard`, `permissions`, plus `settings` as a baseline). The CLI runs `uv sync`, `npm install`, and `alembic upgrade head` for you.
+`--yes` accepts the defaults (SQLite, no multi-tenancy, the `standard` preset: `auth`, `users`, `dashboard`, `permissions`). The CLI runs `uv sync`, `npm install`, and `alembic upgrade head` for you.
 
 For an interactive run with prompts, drop the `--yes`. For a preset + extras: `smpy new myapp --preset standard --with background_tasks,file_storage --yes`.
 
@@ -32,7 +32,7 @@ The API and Vite dev servers start side by side. Visit:
 - `http://localhost:8000` — landing page
 - `http://localhost:8000/users/login` — sign-in screen
 - `http://localhost:8000/dashboard` — the authenticated home (log in first)
-- `http://localhost:8000/settings/modules` — the admin settings UI (log in first)
+- `http://localhost:8000/settings/modules` — the admin settings UI (log in first; only when the `settings` module is installed, e.g. the `full` preset or `--with settings`)
 
 ## 4. Create an admin
 
@@ -51,32 +51,29 @@ smpy create-module orders --dest modules/orders
 uv add ./modules/orders
 ```
 
-This generates `modules/orders/` with:
+This generates a publishable starter module at `modules/orders/` with:
 
 - `pyproject.toml` — `[project.entry-points.simple_module]` → `orders.module:OrdersModule`
 - `package.json` + `tsconfig.json` — JS workspace metadata so `tsc --noEmit` covers the module's `.tsx` pages.
-- `orders/module.py` — `ModuleBase` subclass with `meta = ModuleMeta(name="Orders", ...)`.
-- `orders/models.py` — `Order` SQLModel table with `AuditMixin`.
-- `orders/contracts/schemas.py` — `OrderCreate`, `OrderOut` DTOs.
-- `orders/service.py` — CRUD implementation.
+- `orders/module.py` — `ModuleBase` subclass with `meta = ModuleMeta(name="Orders", ...)`, wiring `register_routes` and `register_settings`.
 - `orders/services.py` — module-scoped state container (stored on `app.state.orders` by `register_settings`).
-- `orders/deps.py` — FastAPI dependencies.
-- `orders/endpoints/api.py` — REST endpoints at `/api/orders`.
-- `orders/endpoints/views.py` — Inertia endpoints at `/orders`.
-- `orders/pages/Browse.tsx`, `Create.tsx`, `Edit.tsx` — React pages.
-- `orders/locales/en.json` — translation namespace.
-- `tests/test_orders.py` — pytest smoke test.
+- `orders/settings.py` — the module's `pydantic_settings` settings class.
+- `orders/endpoints/api.py` — starter REST endpoints at `/api/orders`.
+- `orders/pages/` — empty page dir; add `.tsx` pages (and a `register_routes` view router) as you build views.
+- `tests/test_module.py` — pytest smoke test.
+
+You add the domain model (`models.py`), DTOs (`contracts/`), service, Inertia views, and pages yourself — the [first-module guide](/guide/first-module) walks through that.
 
 `uv add ./modules/orders` adds the package to your app's dependencies; on the next `uv sync` (which `uv add` also runs) the entry point is registered and the module becomes discoverable on next boot.
 
 ## 6. Generate a migration
 
 ```bash
-uv run alembic revision --autogenerate -m "add orders tables"
+make migration msg="add orders tables"
 make migrate
 ```
 
-Alembic's autogenerate picks up the new `orders_*` tables and writes `migrations/versions/XXXX_add_orders_tables.py`. Add `branch_labels = ("orders",)` to that revision so you can later `alembic downgrade orders@base` to roll the module back in isolation.
+`make migration` runs Alembic from the host directory (where `alembic.ini` lives). Autogenerate picks up the new `orders_*` tables and writes `host/migrations/versions/XXXX_add_orders_tables.py`. Add `branch_labels = ("orders",)` to that revision so you can later `alembic downgrade orders@base` to roll the module back in isolation.
 
 ## 7. Hit the module
 
diff --git a/docs/index.md b/docs/index.md
index 54cfcd51..1a09a3c4 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -26,7 +26,7 @@ features:
     link: /guide/first-module
     linkText: Build a module
   - title: Use a bundled module
-    details: Eight first-party modules ship with the framework — auth, users, permissions, settings, file_storage, background_tasks, feature_flags, dashboard.
+    details: Ten first-party modules ship with the framework — auth, users, keycloak, permissions, settings, file_storage, background_tasks, feature_flags, audit_log, dashboard.
     link: /modules/
     linkText: Browse modules
   - title: Operate it in production
diff --git a/docs/module-authoring.md b/docs/module-authoring.md
index ec771c33..59575de4 100644
--- a/docs/module-authoring.md
+++ b/docs/module-authoring.md
@@ -85,7 +85,7 @@ version, raising `FrameworkVersionError` with the offending modules named.
 - `create_module_base`, `build_module_metadata`, `make_include_object`
 - Model mixins: `AuditMixin`, `SoftDeleteMixin`, `MultiTenantMixin`,
   `VersionedMixin`
-- `build_app()` entry point
+- `create_app()` entry point (`simple_module_hosting`)
 
 **Internal** (free to change without bumping major):
 
@@ -169,8 +169,10 @@ tenant explicitly: `registry.is_enabled(FLAG_BULK_IMPORT.name, tenant_id=tenant)
 
 Each module's settings are loaded via its `register_settings(app)` hook.
 Convention: read environment variables under the prefix `SM_<MODULE>_`
-(e.g. `SM_AUTH_CLIENT_ID`) and store the result on
-`app.state.<module_name_lower>_settings`. Hosts can declare
+(e.g. `SM_AUTH_CLIENT_ID`) and store the result on a module-owned object at
+`app.state.<module_package_lower>` (e.g. `app.state.auth`, `app.state.users`).
+The `SM012` diagnostic looks for exactly that attribute, so the `_settings`
+suffix some older modules used is not recognised. Hosts can declare
 `SM_MODULES_ENABLED='["Auth","MyModule"]'` to load only a subset of
 installed modules.
 
diff --git a/docs/modules/audit_log.md b/docs/modules/audit_log.md
new file mode 100644
index 00000000..0f70c279
--- /dev/null
+++ b/docs/modules/audit_log.md
@@ -0,0 +1,142 @@
+# audit_log
+
+Automatic field-level audit trail for every SQLModel entity in the app. Each create / update / delete / soft-delete is captured in `audit_log_audit_entry` with the changed fields, the user who made the change, and the request correlation id — **no instrumentation required in module code**. Entities opt out, they don't opt in.
+
+## ModuleMeta
+
+| Field | Value |
+|---|---|
+| `name` | `AuditLog` |
+| `route_prefix` | `/api/audit_log` |
+| `view_prefix` | `/audit_log` |
+| `depends_on` | `["Users"]` |
+
+## How capture works
+
+The module doesn't observe changes itself — the DB layer does. On `on_startup` it sets `app.state.sm.db.audit_callback = audit_callback`; on `on_shutdown` it clears it. While that callback is set, the framework's session listeners run a **two-phase capture**:
+
+1. **Phase 1 — `before_flush`.** `snapshot_changes()` walks `session.new` / `session.dirty` / `session.deleted` and records a diff *while SQLAlchemy attribute history is still intact* (it gets wiped after flush). For new rows the diff holds an object reference, not an id, because a DB-assigned PK (e.g. an integer `AUTOINCREMENT` / `SERIAL` id) isn't populated yet. The pending list is stashed on `session.info`.
+2. **Phase 2 — `after_flush_postexec`.** Once INSERTs have executed and PKs are populated on the live objects, `finalize_records()` resolves the now-stable `entity_id` and hands the records to the module's `audit_callback`, which turns each into an `AuditEntry` row.
+
+The two-phase split is why integer-PK entities record the real id instead of an empty string. `AuditEntry` itself sets `__audit_exclude__ = True`, so writing audit rows doesn't recursively produce more audit rows.
+
+The `user_id` comes from the `current_user_id` ContextVar that `AuthMiddleware` sets per request; the `correlation_id` comes from the request-logging correlation-id ContextVar when the hosting layer is present (both are `None` outside a request, e.g. CLI / background writes).
+
+### What gets recorded
+
+| Action | When |
+|---|---|
+| `created` | object in `session.new` |
+| `updated` | object in `session.dirty` with real column changes (empty diffs are skipped) |
+| `deleted` | object in `session.deleted` (hard delete) |
+| `soft_deleted` | a `SoftDeleteMixin` row the soft-delete listener moved into `session.new` with `is_deleted=True` |
+
+`changes` is a list of `{field, new}` (creates) or `{field, old, new}` (updates) entries; deletes and soft-deletes carry an empty change list. Column values are normalised to JSON-safe scalars (non-primitives are stringified).
+
+## Opting out
+
+Auditing is on by default for every table. Two escape hatches, both class attributes read off the model:
+
+```python
+from typing import ClassVar
+from sqlmodel import Field
+from simple_module_db.base import create_module_base
+from simple_module_db.mixins import AuditMixin
+
+Base = create_module_base("auth")
+
+
+class Credential(Base, AuditMixin, table=True):
+    # Skip specific sensitive columns.
+    __audit_exclude_fields__: ClassVar[set[str]] = {"password_hash"}
+
+    id: int | None = Field(default=None, primary_key=True)
+    user_id: str
+    password_hash: str
+
+
+class Cache(Base, table=True):
+    # Skip the table entirely.
+    __audit_exclude__ = True
+```
+
+Primary-key columns and the bookkeeping fields injected by `AuditMixin` (`created_at`, `updated_at`, `created_by`, `updated_by`) and `SoftDeleteMixin` (`is_deleted`, `deleted_at`, `deleted_by`) are excluded from diffs automatically.
+
+## Routes
+
+### API
+
+```python
+GET /api/audit_log/
+```
+
+Requires `audit_log.view`. Returns `AuditEntryList`. Query filters (all optional): `entity_type`, `entity_id`, `action`, `user_id`, `from_date`, `to_date`, `page` (≥1), `page_size` (1–200, default 50). Results are ordered newest-first (`created_at` desc).
+
+### View
+
+| Method + path | Inertia component | Permission |
+|---|---|---|
+| `GET /audit_log/` | `AuditLog/Browse` | `audit_log.view` |
+
+The browse route takes the same filter set as the API. It additionally returns the list of distinct `entity_type` values seen so far, to populate the filter dropdown. Pagination params are sanitised rather than validated — a bad `page` / `page_size` falls back to the default instead of erroring.
+
+## Public contracts
+
+```python
+from audit_log.contracts.schemas import AuditEntryRead, AuditEntryList
+```
+
+| Class | Purpose |
+|---|---|
+| `AuditEntryRead` | One audit row: `id`, `entity_type`, `entity_id`, `action`, `changes` (`list[dict]`), `user_id`, `correlation_id`, `created_at`. |
+| `AuditEntryList` | Paginated envelope: `items`, `total`, `page`, `page_size`. |
+
+## Models
+
+`AuditEntry` (table `audit_log_audit_entry`)
+
+| Column | Type | Notes |
+|---|---|---|
+| `id` | `UUID` | PK |
+| `entity_type` | `str(255)` | indexed; the model class name |
+| `entity_id` | `str(255)` | indexed; the resolved PK as a string |
+| `action` | `str(20)` | `created` / `updated` / `deleted` / `soft_deleted` |
+| `changes` | JSON | list of field diffs |
+| `user_id` | `str(255) \| None` | indexed; from the request's `current_user_id` |
+| `correlation_id` | `str(255) \| None` | request correlation id |
+| `created_at` | `datetime` | indexed; tz-aware, `server_default = now()` |
+
+The table itself carries `__audit_exclude__ = True` so audit writes never re-enter the capture loop.
+
+## Permissions
+
+| Code | Purpose |
+|---|---|
+| `audit_log.view` | read the audit trail (API + browse page) |
+
+There is no write permission — the trail is append-only and written by the framework, never edited through the UI.
+
+## Menu
+
+| Label | URL | Icon | Section | Group | Order |
+|---|---|---|---|---|---|
+| `Audit Log` | `/audit_log` | `scroll-text` | `SIDEBAR` | `System` | `210` |
+
+## Inertia pages
+
+- `AuditLog/Browse.tsx` — paginated, filterable table of audit entries.
+- Components: `components/FilterBar.tsx`.
+
+## Locales
+
+Top-level keys in `audit_log/locales/en.json` (namespace `audit_log`): `browse` (page chrome + pagination), `filters` (filter-bar labels), `table` (column headers), `actions` (per-action labels, where `soft_deleted` renders as "Archived"), `changes` (diff rendering, `{count} fields set`, system-user / no-change placeholders).
+
+## Enabling
+
+The module is discovered automatically once `simple_module_audit_log` is installed (entry point `audit_log = "audit_log.module:AuditLogModule"`). Grant `audit_log.view` to your admin role and entries start appearing for every entity that hasn't opted out. To install as a distributed package:
+
+```bash
+pip install simple_module_audit_log
+```
+
+It depends on the [`users`](/modules/users) module (for the menu/permission wiring and the request-scoped `user_id`).
diff --git a/docs/modules/auth.md b/docs/modules/auth.md
index 450a8c15..ae4b346e 100644
--- a/docs/modules/auth.md
+++ b/docs/modules/auth.md
@@ -1,8 +1,8 @@
 # auth
 
-A minimal public-API module. It owns the import paths every *other* module uses to read the current user (`UserContext`, `get_current_user`, `require_permission`) — but ships **no routes, no models, no UI**. The actual login/session/middleware logic lives in [`users`](/modules/users).
+A minimal public-API module. It owns the import paths every *other* module uses to read the current user (`UserContext`, `AuthProvider`, `get_current_user`, `require_permission`) and ships the provider-agnostic `AuthMiddleware` — but **no routes, no models, no UI**. The actual login/session logic lives in an auth-provider module ([`users`](/modules/users) for local accounts + OAuth, or [`keycloak`](/modules/keycloak) for Keycloak SSO).
 
-The split exists so you can swap out the users module (e.g. to plug in OAuth or LDAP) without churning every consumer's import paths.
+Auth is **pluggable**: exactly one installed module registers an `AuthProvider` implementation on `app.state.auth.auth_provider`, and `AuthMiddleware` delegates to it on every request. The split exists so you can swap authentication backends without churning every consumer's import paths. Diagnostics enforce the invariant — `SM020` errors if two auth-provider modules are installed, `SM021` warns if none is.
 
 ## ModuleMeta
 
@@ -16,21 +16,22 @@ The split exists so you can swap out the users module (e.g. to plug in OAuth or
 ## Public contracts
 
 ```python
-from auth.contracts.schemas import UserContext
+from auth.contracts import UserContext, AuthProvider
 ```
 
-`UserContext` — frozen-ish dataclass populated by the `AuthMiddleware` (in `users`). Fields:
+`UserContext` — a dataclass describing the authenticated user. Only set on `request.state.user` when a request is authenticated; downstream code reads it via `get_current_user` / `CurrentUser` (which 401 when it's absent). Fields:
 
 | Field | Type | Notes |
 |---|---|---|
-| `id` | `UUID \| None` | `None` for anonymous requests |
-| `email` | `str` | empty string when anonymous |
-| `full_name` | `str` | |
+| `id` | `str` | user id, stringified |
+| `email` | `str` | |
+| `name` | `str` | display name — `full_name or email` of the user |
 | `roles` | `list[str]` | role names, e.g. `["admin"]` |
-| `tenant_id` | `str \| None` | only set when `SM_MULTI_TENANT=true` |
-| `is_authenticated` | `bool` | property — `id is not None` |
+| `tenant_id` | `str \| None` | only set when multi-tenant |
 
-It also exposes `to_session_dict()` / `from_session_dict()` for the middleware to (de)serialise itself into the session cookie.
+Helpers: `has_role(role)` / `has_any_role(roles)` for in-handler role checks; `from_user(user)` builds a context from a duck-typed user object (`.id`, `.email`, `.full_name`, `.roles[*].name`, `.tenant_id`); `to_session_dict()` / `from_session_dict()` (de)serialise it into the signed session cookie.
+
+`AuthProvider` is the `Protocol` an auth-provider module implements (`resolve_user`, `get_login_url`, `get_logout_url`, `get_public_paths`, `is_bearer_request`) — see [Pluggable auth](#pluggable-auth) below.
 
 ## Dependencies for endpoints
 
@@ -42,7 +43,7 @@ from auth.deps import CurrentUser, get_current_user, require_permission
 |---|---|
 | `CurrentUser` (`Annotated` alias) | FastAPI dependency that returns the active `UserContext`. Raises 401 if `request.state.user` isn't set. |
 | `get_current_user(request, t)` | The underlying callable. Use this when you need to compose it manually. |
-| `require_permission("orders.view", "orders.edit")` | Returns a dependency that 403s if the user is missing **any** of the listed permissions. The `admin` role bypasses the check. |
+| `require_permission("orders.view", "orders.edit")` | Returns a dependency that passes if the user has **any** of the listed permissions, and 403s only if they have **none**. The `admin` role bypasses the check. |
 
 ## Example: protecting a route
 
@@ -67,6 +68,23 @@ async def delete_order(order_id: int, user: CurrentUser) -> None:
 
 For permission checks that need to honour **direct user grants** (not just role-derived perms), use [`RequiresPermission` from the permissions module](/modules/permissions#using-requirespermission) instead.
 
+## Pluggable auth
+
+`AuthModule.register_settings` puts an empty `AuthState` on `app.state.auth` (holding `auth_provider` and `principal_resolvers`), and `register_middleware` installs `AuthMiddleware`. On each HTTP request the middleware:
+
+1. Skips authentication for public paths — framework defaults (`/health`, `/static/`, `/api/docs`, `/api/redoc`, `/openapi.json`, `/i18n/`, and the exact path `/`), method-aware rules contributed via the [`register_public_routes`](/framework/lifecycle) hook (plus the `SM_AUTH_PUBLIC_PATHS` host escape hatch), and the provider's own `get_public_paths()` (prefix-only, kept for back-compat).
+2. Calls `provider.resolve_user(request)` (the `AuthProvider` registered by `users` or `keycloak`).
+3. On a miss, walks the **principal-resolver chain** (`app.state.auth.principal_resolvers`) in order — async callables `(Request) -> UserContext | None` for extra credential sources (PAT bearer tokens, API keys). The first non-`None` wins; each is wrapped in `try/except` so a raising resolver is treated as no-match.
+4. If still unauthenticated and the path isn't public: returns `401` JSON for `/api/*` or bearer requests, otherwise stashes `next` in the session and redirects to `provider.get_login_url(request)`.
+
+When a user is resolved it's written to `request.state.user` and the `current_user_id` ContextVar (for audit listeners).
+
+Register an extra resolver from an app's `on_startup`:
+
+```python
+app.state.auth.principal_resolvers.append(my_pat_resolver)
+```
+
 ## Locales
 
 | Key | Default |
diff --git a/docs/modules/index.md b/docs/modules/index.md
index d2c3e2c5..1d67d9df 100644
--- a/docs/modules/index.md
+++ b/docs/modules/index.md
@@ -1,16 +1,18 @@
 # Bundled modules
 
-simple_module_python ships with eight first-party modules. Each is a regular Python package — same shape as a module you'd write yourself — registered through the `simple_module` entry point and discovered at boot. They are independent: install only what you need.
+simple_module_python ships with ten first-party modules. Each is a regular Python package — same shape as a module you'd write yourself — registered through the `simple_module` entry point and discovered at boot. They are independent: install only what you need.
 
 | Module | Depends on | What it provides |
 |---|---|---|
-| [`auth`](/modules/auth) | — | Tiny public surface (`UserContext`, `get_current_user`, `require_permission`) other modules import. The actual login/session logic lives in `users`. |
-| [`users`](/modules/users) | `auth` | Email + password auth, sessions, roles, invites, password reset, email verification, admin UI, mailer backends, `smpy users create-admin`. |
+| [`auth`](/modules/auth) | — | Tiny public surface (`UserContext`, `AuthProvider`, `get_current_user`, `require_permission`) other modules import, plus the provider-agnostic `AuthMiddleware` and principal-resolver chain. The actual login/session logic lives in an auth-provider module (`users` or `keycloak`). |
+| [`users`](/modules/users) | `auth` | Email + password auth, OAuth/OIDC (Google, GitHub, Microsoft/Entra ID, generic OIDC), sessions, roles, invites, password reset, email verification, admin UI, mailer backends, `smpy users create-admin`. |
+| [`keycloak`](/modules/keycloak) | `auth`, `settings` | Alternative auth provider: Keycloak OIDC single sign-on. |
 | [`permissions`](/modules/permissions) | `auth`, `users` | Role / direct-grant assignment store + admin UI; `RequiresPermission` dependency that honours both forms. |
 | [`settings`](/modules/settings) | — | DB-backed key/value store with system / tenant / user precedence; per-module pydantic settings registration; hot reload; `smpy settings` CLI. |
 | [`feature_flags`](/modules/feature_flags) | — | Runtime feature toggles with system + tenant overrides. |
 | [`file_storage`](/modules/file_storage) | `settings` | Pluggable file storage (filesystem, S3-compatible) with upload validation, presigned URLs, browse/download/delete UI. |
 | [`background_tasks`](/modules/background_tasks) | `users` | Celery + Redis workers, persistent task history, retry, stuck-task sweep, live worker dashboard. |
+| [`audit_log`](/modules/audit_log) | `users` | Automatic field-level audit trail for SQLModel entities, with an admin UI to browse change history. |
 | [`dashboard`](/modules/dashboard) | `users` | Authenticated landing page with system overview (user counts, module list, health checks). |
 
 ## How modules are wired in
diff --git a/docs/modules/keycloak.md b/docs/modules/keycloak.md
new file mode 100644
index 00000000..066f9378
--- /dev/null
+++ b/docs/modules/keycloak.md
@@ -0,0 +1,130 @@
+# keycloak
+
+A pluggable **OIDC auth provider** backed by Keycloak. Install it *instead of* [`users`](/modules/users) to delegate identity — login, users, and roles — to Keycloak. Browser users are redirected to Keycloak's hosted login; API/mobile clients send a `Bearer` access token that the module validates against Keycloak's JWKS.
+
+## ModuleMeta
+
+| Field | Value |
+|---|---|
+| `name` | `Keycloak` |
+| `route_prefix` | `/api/keycloak` |
+| `view_prefix` | `/keycloak` |
+| `depends_on` | `["Auth", "Settings"]` |
+
+The module sets the class flag `_is_auth_provider = True`, which is what the auth-provider diagnostics count (see [below](#auth-provider-diagnostics)).
+
+## The AuthProvider contract
+
+`keycloak` implements the [`auth`](/modules/auth) module's `AuthProvider` protocol (`auth.contracts.provider.AuthProvider`). The contract is:
+
+```python
+@runtime_checkable
+class AuthProvider(Protocol):
+    name: str
+    async def resolve_user(self, request: Request) -> UserContext | None: ...
+    def get_login_url(self, request: Request, next_url: str | None = None) -> str: ...
+    def get_logout_url(self, request: Request) -> str: ...
+    def get_public_paths(self) -> tuple[tuple[str, ...], tuple[str, ...]]: ...
+    def is_bearer_request(self, request: Request) -> bool: ...
+```
+
+`KeycloakAuthProvider` (`name = "keycloak"`) registers itself on `app.state.auth.auth_provider` during `register_settings`. Exactly one module — `users` *or* `keycloak`, not both — may do this.
+
+### Slotting into the principal-resolver chain
+
+The provider-agnostic `AuthMiddleware` (in `auth`) runs on every request and:
+
+1. Calls `provider.resolve_user(request)`. The Keycloak provider:
+   - If there's an `Authorization: Bearer <token>` header, validates the JWT against the cached JWKS and maps claims → `UserContext`.
+   - Otherwise rehydrates `UserContext.from_session_dict(...)` from the browser session cookie (populated by the OIDC callback).
+2. If the provider returns `None`, it falls through to the registered **principal resolvers** (`app.state.auth.principal_resolvers`), trying each until one matches.
+3. If still unresolved and the path isn't public: `/api/*` and bearer requests get a `401` JSON; browser requests are redirected to `provider.get_login_url(...)` (`/keycloak/login`), with the original URL stashed in the session as `next`.
+
+`get_public_paths()` exempts `/keycloak/login`, `/keycloak/logout`, and `/api/keycloak/auth/` from auth.
+
+## Bearer-token validation
+
+`JWKSCache` (`keycloak/jwks.py`) caches Keycloak's RS256 public signing keys (`/realms/<realm>/protocol/openid-connect/certs`) and validates tokens with PyJWT, checking signature, `issuer`, and `audience` (the `client_id`). It refetches once on a cache miss / unknown `kid`, so Keycloak key rotation is handled gracefully. The cache is built in `on_startup` (only when `server_url` and `realm` are configured) and attached to the provider.
+
+On a valid bearer token the provider upserts a `KeycloakUserCache` row keyed by the Keycloak `sub`, so each external identity maps to a stable framework UUID, then returns a `UserContext` whose `id` is that UUID.
+
+## Browser login flow (OIDC)
+
+`OIDCClient` (`keycloak/oidc.py`) wraps the realm's authorization-code endpoints.
+
+| Method + path | What |
+|---|---|
+| `GET /keycloak/login` | Inertia `Keycloak/Login` page (auto-redirects to the IdP). |
+| `POST /keycloak/logout` | Clears the session, redirects to Keycloak's RP-initiated logout (`post_logout_redirect_uri` back to `/keycloak/login`, with `id_token_hint`). |
+| `GET /api/keycloak/auth/login` | Builds the authorization URL (random `state` + `nonce` stored in session) and 302s to Keycloak. |
+| `GET /api/keycloak/auth/callback` | Verifies `state`, exchanges the `code` for tokens, validates the access token, upserts the user cache, writes `UserContext` + the id token to the session, then redirects to `next` (or `login_redirect_url`). |
+
+## Settings
+
+DB-backed via `register_module_settings("keycloak", KeycloakSettings, ...)`; bootstrap defaults come from `SM_KEYCLOAK_*` env vars. State lives at `app.state.keycloak` (`KeycloakState`: `settings`, `jwks_cache`).
+
+| Field | Env var | Default | Notes |
+|---|---|---|---|
+| `server_url` | `SM_KEYCLOAK_SERVER_URL` | `""` | Keycloak base URL |
+| `realm` | `SM_KEYCLOAK_REALM` | `""` | realm name |
+| `client_id` | `SM_KEYCLOAK_CLIENT_ID` | `""` | also the expected JWT audience |
+| `client_secret` | `SM_KEYCLOAK_CLIENT_SECRET` | `""` | confidential-client secret |
+| `roles_claim_path` | — | `"realm_access.roles"` | dotted path to the roles array in the token |
+| `admin_role` | — | `"admin"` | |
+| `login_redirect_url` | — | `"/dashboard/"` | post-login landing |
+| `jwks_cache_ttl_seconds` | — | `3600` | signing-key cache TTL |
+| `role_mapping` | — | `{"admin": "admin", "user": "user"}` | Keycloak realm role → framework permission/role |
+
+`server_url`, `realm`, `client_id`, and `client_secret` are **required in production** — `KeycloakSettings` raises at boot if any is missing outside a non-prod environment. They may be left blank in development and filled in later through the settings admin UI.
+
+### Role mapping
+
+`role_mapping` translates Keycloak realm roles (read from `roles_claim_path`) into the framework's role names. Roles the user has that aren't in the mapping are dropped, so only explicitly mapped roles reach the `UserContext`.
+
+## Models
+
+`KeycloakUserCache` (table `keycloak_user_cache`)
+
+| Column | Type | Notes |
+|---|---|---|
+| `id` | `UUID` | PK; the stable framework user id |
+| `keycloak_sub` | `str` | unique, indexed; the Keycloak `sub` claim |
+| `email` | `str` | from the token |
+| `full_name` | `str \| None` | from `preferred_username` |
+| `last_login_at` | `datetime \| None` | refreshed on each resolve |
+
+## Menu
+
+| Label | URL | Icon | Section | Order | Method |
+|---|---|---|---|---|---|
+| `Logout` | `/keycloak/logout` | `log-out` | `USER_DROPDOWN` | `999` | `post` |
+
+## Inertia pages
+
+- `Keycloak/Login.tsx` — the "redirecting to identity provider" splash.
+- `Keycloak/LoggedOut.tsx` — post-logout confirmation.
+
+## Locales
+
+Top-level keys in `keycloak/locales/en.json` (namespace `keycloak`): `login`, `logout`, `errors`.
+
+## Auth-provider diagnostics
+
+The framework's module diagnostics (run by `make doctor` and at prod boot) count modules with `_is_auth_provider = True`:
+
+- **SM020** (error) — more than one auth provider installed (e.g. `users` *and* `keycloak`). Install only one.
+- **SM021** (warning) — no auth provider installed at all.
+
+In production these errors fail boot. So swapping to Keycloak means **removing `simple_module_users`** from the host's dependencies, not running it alongside.
+
+## Enabling
+
+Add the package to the host instead of `simple_module_users`:
+
+```toml
+dependencies = [
+    "simple_module_keycloak==0.0.17",
+]
+```
+
+Then `uv sync --all-packages`. The entry point (`keycloak = "keycloak.module:KeycloakModule"`) is discovered automatically; set the four `SM_KEYCLOAK_*` env vars (or configure them via the settings admin UI after first boot). It depends on the [`auth`](/modules/auth) and [`settings`](/modules/settings) modules.
diff --git a/docs/modules/permissions.md b/docs/modules/permissions.md
index fa09439c..f100a788 100644
--- a/docs/modules/permissions.md
+++ b/docs/modules/permissions.md
@@ -57,11 +57,11 @@ async def delete_order(order_id: int) -> None:
     ...
 ```
 
-`RequiresPermission(*permissions)` 403s unless the request's user has each listed key, considering:
+`RequiresPermission(permission)` takes a **single** permission key and 403s unless the request's user holds it, considering:
 
-1. The keys assigned to any of the user's roles.
-2. The keys assigned directly to the user.
-3. The implicit grant of every permission to anyone with the `admin` role.
+1. The keys assigned to any of the user's roles (read from the request-cached `resolved_permissions`).
+2. The keys assigned directly to the user (`permissions_user_permission`).
+3. The implicit `WILDCARD` grant — the `admin` role is synced to hold every permission key at startup, so admins pass any check.
 
 For something tied to *only* role membership (no direct grants), use `auth.deps.require_permission` instead — it's a hair cheaper.
 
diff --git a/docs/modules/users.md b/docs/modules/users.md
index cdbc2ac2..c50976b5 100644
--- a/docs/modules/users.md
+++ b/docs/modules/users.md
@@ -1,6 +1,6 @@
 # users
 
-The auth + user-management module: email/password login, sessions, registration, invites, password reset, email verification, role assignment, admin UI, mailer backends, and the `AuthMiddleware` that other modules depend on for `request.state.user`.
+The default auth provider + user-management module: email/password login, OAuth/OIDC sign-in, sessions, registration, invites, password reset, email verification, role assignment, admin UI, and mailer backends. It registers a `UsersAuthProvider` on `app.state.auth.auth_provider`, which the [`auth`](/modules/auth) module's `AuthMiddleware` delegates to for `request.state.user`. (It's one of two bundled auth providers — [`keycloak`](/modules/keycloak) is the alternative; install exactly one.)
 
 ## ModuleMeta
 
@@ -15,10 +15,11 @@ The auth + user-management module: email/password login, sessions, registration,
 
 The module is built on [`fastapi-users`](https://fastapi-users.github.io/) for password hashing, registration, password reset, and verification. On top of that it layers:
 
-- A signed session cookie (`sm_auth` by default) — `AuthMiddleware` reads it on every request and populates `request.state.user`.
+- A signed session cookie (`sm_auth` by default) — the auth module's `AuthMiddleware` calls `UsersAuthProvider.resolve_user`, which reads it on every request and populates `request.state.user`. Bearer tokens (`Authorization: Bearer <token>`) resolve against `users_access_token`.
+- OAuth / OIDC sign-in (Google, GitHub, Microsoft/Entra ID, and any generic OIDC provider) — see [OAuth providers](#oauth-providers).
 - An invite flow — admins generate an invite link; the recipient sets their password via `POST /api/users/auth/accept-invite`.
-- `LoginRateLimiter` — N failures within a window triggers a cooldown per email.
-- `AuthRateLimiter` — global rate limit across signup / forgot-password / verify endpoints.
+- `LoginRateLimiter` — N failures within a window triggers a cooldown per `email::ip` key.
+- `ThroughputLimiter` — per-IP rate limit across register / forgot-password / accept-invite / verify-token endpoints.
 
 ### Auth endpoints
 
@@ -27,10 +28,12 @@ The module is built on [`fastapi-users`](https://fastapi-users.github.io/) for p
 | `POST /api/users/auth/login` | `OAuth2PasswordRequestForm` | sets `sm_auth` cookie + `session["user_id"]`; rate-limited per email |
 | `POST /api/users/auth/register` | `UserCreate` | gated by `users.allow_signup`; rate-limited |
 | `POST /api/users/auth/forgot-password` | `PasswordReset` | rate-limited |
-| `POST /api/users/auth/reset-password/{token}` | `ResetPassword` | |
+| `POST /api/users/auth/reset-password` | `{token, password}` | |
 | `POST /api/users/auth/request-verify-token` | `RequestVerifyToken` | rate-limited |
 | `POST /api/users/auth/verify` | `VerifyRequest` | |
 | `POST /api/users/auth/accept-invite` | `AcceptInviteRequest` | sets password + signs the user in |
+| `GET /api/users/auth/{provider}/login` | — | OAuth: redirect to the IdP (`provider` ∈ configured set) |
+| `GET /api/users/auth/{provider}/callback` | `?code=&state=` | OAuth: find-or-create user, set cookie, 303 to `login_redirect_url` |
 
 ### Self-service endpoints
 
@@ -114,7 +117,11 @@ from users.contracts.events import (
 
 `UserRole` (table `users_user_role`) — composite-PK join table with `assigned_at`, `assigned_by`. The `(user_id, role_id)` PK is user-id-first; a separate index covers reverse lookups by `role_id`.
 
-`UserAccessToken` — fastapi-users API tokens (rare path; sessions are the primary auth).
+`UserAccessToken` (table `users_access_token`) — bearer API tokens; resolved by `UsersAuthProvider` on `Authorization: Bearer` requests (sessions remain the primary browser auth).
+
+`OAuthAccount` (table `users_oauth_account`) — linked OAuth/OIDC accounts: `oauth_name`, `account_id`, `account_email`, `access_token`, `refresh_token`, `expires_at`.
+
+`RefreshToken` (table `users_refresh_token`) — opaque refresh tokens for the bearer flow: `token` (PK), `user_id`, `created_at`, `expires_at`, `revoked_at`.
 
 Two pre-seeded roles get fixed UUIDs so other modules can reference them safely:
 
@@ -143,6 +150,8 @@ Everything else is DB-backed (initial values are pydantic defaults; edit at `/se
 | `login_redirect_url` | `"/dashboard/"` (if the Dashboard module isn't installed, auto-falls back to the first other module that exposes view routes, or `/` only as a last resort) |
 | `reset_password_token_lifetime_seconds` | `3600` |
 | `verification_token_lifetime_seconds` | `604_800` (7 days) |
+| `bearer_token_lifetime_seconds` | `900` (15 min) |
+| `refresh_token_lifetime_seconds` | `2_592_000` (30 days) |
 | `cookie_name` | `"sm_auth"` |
 | `cookie_max_age_seconds` | `1_209_600` (14 days) |
 | `cookie_secure` | `True` (flipped to `False` in dev at startup) |
@@ -156,6 +165,10 @@ Everything else is DB-backed (initial values are pydantic defaults; edit at `/se
 | `auth_rate_limit_attempts` | `10` |
 | `auth_rate_limit_window_seconds` | `300` |
 | `bootstrap_email`, `bootstrap_password`, `bootstrap_user_email`, `bootstrap_user_password` | `""` — see [Bootstrap](#bootstrap-the-first-admin) |
+| `oauth_google_client_id` / `oauth_google_client_secret` | `""` — Google OAuth |
+| `oauth_github_client_id` / `oauth_github_client_secret` | `""` — GitHub OAuth |
+| `oauth_microsoft_client_id` / `oauth_microsoft_client_secret` / `oauth_microsoft_tenant` | `""` / `""` / `"common"` — Microsoft (Entra ID) |
+| `oauth_oidc_client_id` / `oauth_oidc_client_secret` / `oauth_oidc_discovery_url` / `oauth_oidc_display_name` | `""` / `""` / `""` / `"OIDC"` — generic OIDC |
 
 ## Permissions
 
@@ -216,15 +229,33 @@ Two paths to seed the first admin:
 
 `build_mailer(settings)` returns the right instance based on `users.mailer`.
 
-## AuthMiddleware
+## OAuth providers
+
+OAuth/OIDC sign-in is **DB-settings-driven**: a provider is enabled simply by setting its `client_id` + `client_secret` (and, for generic OIDC, a discovery URL) in the settings UI at `/settings/modules/users`. No code change or restart — `register_event_handlers` rebuilds the client cache (`app.state.users.oauth_clients`) on the `SettingsReloaded` event, so changes take effect live. Providers with no credentials are silently skipped.
+
+Built-in provider keys (the `{provider}` URL segment):
+
+| Provider | Key | Notes |
+|---|---|---|
+| Google | `google` | |
+| GitHub | `github` | |
+| Microsoft (Entra ID) | `microsoft` | `oauth_microsoft_tenant`: `"common"` (any account), `"organizations"` (work/school), or a tenant GUID |
+| Generic OIDC | `oidc` | any provider exposing a discovery URL (Keycloak, Authentik, Auth0, Zitadel, …); discovery failure logs + disables rather than breaking boot |
+
+A single dispatcher pair (`/api/users/auth/{provider}/login` + `/callback`) serves every provider; the client is resolved per request from the cache. The `/callback` returns a 303 redirect (not the stock fastapi-users 204) so Inertia lands on a real page, with the auth cookie attached. Find-or-create + email association goes through `UserManager.oauth_callback` (`associate_by_email=True`, `is_verified_by_default=True`); state CSRF uses the signed session cookie. Linked accounts are stored in `users_oauth_account`.
+
+## UsersAuthProvider
+
+`UsersAuthProvider` (registered on `app.state.auth.auth_provider` in `register_settings`) is the `AuthProvider` the auth module's `AuthMiddleware` delegates to. On each request `resolve_user`:
 
-Reads `session["user_id"]`, loads the User row with eagerly-loaded roles, builds a `UserContext`, and writes it to `request.state.user`. Caches the context in `session["user_ctx"]` so subsequent requests don't re-query.
+- For a `Bearer` token, looks the token up in `users_access_token` and returns the active user.
+- Otherwise reads `session["user_id"]`, returns the cached context from `session["user_ctx"]` on a hit, else loads the User row with eagerly-loaded roles, builds a `UserContext`, caches it in `session["user_ctx"]`, and clears stale session keys when the user is missing/disabled.
 
-Public paths (no redirect to login):
+`get_login_url()` → `/users/login`, `get_logout_url()` → `/users/logout`. The provider's `get_public_paths()` declares these prefixes anonymous (in addition to the framework defaults `/health`, `/static/`, `/api/docs`, `/api/redoc`, `/openapi.json`, `/i18n/`, `/`):
 
-`/users/login`, `/users/register`, `/users/forgot-password`, `/users/reset-password`, `/users/verify`, `/users/invite/accept`, `/api/users/auth/`, `/api/users/register`, `/health`, `/static/`, `/api/docs`, `/api/redoc`, `/openapi.json`, `/i18n/`, and the exact path `/`.
+`/users/login`, `/users/register`, `/users/forgot-password`, `/users/reset-password`, `/users/verify`, `/users/invite/accept`, `/api/users/auth/`, `/api/users/register`.
 
-Anything else without a session redirects to `/users/login`.
+Anything else without a session redirects to `/users/login` (or returns 401 JSON for `/api/*` / bearer requests).
 
 ## Roles cache
 
@@ -244,5 +275,5 @@ Components:
 ## Notes
 
 - `cookie_secure` is automatically flipped to `False` in dev (`SM_ENVIRONMENT=development`) so login works over plain HTTP. Don't override it in non-dev environments.
-- `LoginRateLimiter` keys by lowercased email, so an attacker spreading attempts across emails won't be slowed down — pair with WAF / IP-based rate limiting in front for that.
+- `LoginRateLimiter` keys login attempts by `lowercased-email::client-ip`. Counters live in-process (no Redis), so a multi-worker deployment has independent counters per worker — swap for a Redis-backed store when running more than one worker.
 - The functional `lower(email)` index makes case-insensitive lookups fast on Postgres; on SQLite the lookup falls back to `LOWER(email) = ?` which still uses the regular index.
diff --git a/docs/reference/deployment.md b/docs/reference/deployment.md
index 15b54844..1dbe3a68 100644
--- a/docs/reference/deployment.md
+++ b/docs/reference/deployment.md
@@ -6,14 +6,14 @@ A production deployment is one FastAPI process (plus optional Celery workers) be
 
 Before serving traffic:
 
-- [ ] `SM_ENVIRONMENT` set to something other than `development`/`test`/`testing`.
+- [ ] `SM_ENVIRONMENT` set to something other than `development`/`testing` (those two are the only values treated as non-prod).
 - [ ] `SM_SECRET_KEY` is a strong random value (not the default).
 - [ ] `SM_DATABASE_URL` points at Postgres (`postgresql+asyncpg://`), not SQLite.
 - [ ] `alembic upgrade head` run against the production DB.
-- [ ] App boot in `SM_ENVIRONMENT=production` mode produces no diagnostic errors. Production boot fails fast on any `SM0XX` ERROR — so a successful start *is* the check.
+- [ ] App boot in a non-development `SM_ENVIRONMENT` starts clean. Module discovery runs strict (missing/invalid `meta` and entry-point failures raise), and the migration check (SM010) aborts boot — so a successful start covers those. The full page/locale/auth-provider diagnostic suite only runs in development, so do a clean dev boot before shipping (see [diagnostic codes](/reference/diagnostic-codes)).
 - [ ] Admin bootstrap complete — an admin user exists and can log in.
 - [ ] Reverse proxy forwards `X-Forwarded-Proto`/`X-Forwarded-For`; configured with `--proxy-headers`.
-- [ ] HTTPS in front of the app (cookie is `Secure` when TLS is present).
+- [ ] HTTPS in front of the app (the session cookie is `HttpOnly`/`SameSite=Lax` but not `Secure` by default — terminate TLS at the proxy).
 - [ ] Log destination configured (`SM_LOG_FORMAT=json` + log shipping).
 
 ## Build
@@ -39,7 +39,8 @@ RUN npm run build
 FROM python:3.12-slim
 WORKDIR /app
 COPY --from=builder /app /app
-COPY --from=frontend /app/client_app/dist /app/client_app/dist
+# Vite builds to ../static/dist relative to client_app, i.e. /app/static/dist
+COPY --from=frontend /app/static/dist /app/static/dist
 CMD ["uv", "run", "uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000", "--proxy-headers"]
 ```
 
@@ -50,8 +51,8 @@ Tune worker count with `--workers N` for multi-CPU boxes, or run behind a proces
 Don't migrate from inside the web container's startup hook — that way lies races when scaling up. Run it as a **one-shot job** before rolling the web tier:
 
 ```bash
-# one-shot container
-uv run --project host alembic upgrade head
+# one-shot container — run from the host project (default workspace scaffold)
+cd host && uv run alembic upgrade head
 
 # then roll web tier
 kubectl rollout restart deployment/web
@@ -64,7 +65,7 @@ The boot-time migration check (`SM010`) will fail cleanly if web starts against
 For small deployments, one web container is plenty. Scale by adding:
 
 - **Web replicas** — stateless; they share state via DB and Redis. Session cookies are signed, so any replica can serve any request.
-- **Celery workers** — `SM_MODULES_ENABLED=background_tasks,<modules with tasks>` keeps workers lean. Run `uv run --project host celery -A background_tasks.celery_app worker -l info`.
+- **Celery workers** — `SM_MODULES_ENABLED=background_tasks,<modules with tasks>` keeps workers lean. Run `uv run celery -A scripts.run_worker:celery worker -l info`.
 - **Celery beat** (scheduler) — exactly one instance, separate deployment.
 
 ## Observability
@@ -75,8 +76,9 @@ For small deployments, one web container is plenty. Scale by adding:
 
 ### Health checks
 
-- `/health` — Kubernetes liveness. Returns 200 if the process is alive; no dependency checks.
-- `/admin/health` — aggregated health with every module's registered checks. Return 503 if any critical check fails. Gate behind `admin.health.view` if you don't want it public.
+- `/health` — returns 200 with `{"status": "healthy", "migration": ...}` (includes the cached migration state). No dependency checks.
+- `/health/live` — Kubernetes liveness. Returns 200 `{"status": "alive"}` if the process is up.
+- `/health/ready` — readiness. Runs every module's registered health checks concurrently and aggregates the worst status into the JSON body (`healthy`/`degraded`/`unhealthy`). Returns 200 regardless — inspect the `status` field rather than the HTTP code.
 
 ### Metrics
 
@@ -84,7 +86,7 @@ Not built in. The framework doesn't expose Prometheus metrics out of the box. If
 
 ## Session cookie
 
-`SessionMiddleware` uses `SM_SECRET_KEY` for signing. `Secure` + `HttpOnly` + `SameSite=Lax` by default. Rotate the secret by:
+`SessionMiddleware` uses `SM_SECRET_KEY` for signing. Starlette's defaults apply: `HttpOnly` + `SameSite=Lax`, but **not** `Secure` (the framework adds the middleware with only `secret_key`, so the cookie isn't restricted to HTTPS — rely on your TLS-terminating proxy). Rotate the secret by:
 
 1. Deploying with a new `SM_SECRET_KEY`.
 2. Expected behavior: existing sessions become invalid. Users sign back in.
@@ -124,11 +126,11 @@ Start `uvicorn` with `--proxy-headers` so it trusts `X-Forwarded-For` for client
 
 ## Static assets
 
-The Vite build outputs to `client_app/dist/`. Serve these via the reverse proxy directly (not through Uvicorn) for better performance:
+The Vite build outputs to `static/dist/` (the app mounts the `static/` dir at `/static`, so built assets live under `/static/dist/`). Serve these via the reverse proxy directly (not through Uvicorn) for better performance:
 
 ```nginx
-location /build/ {
-    alias /var/www/app/client_app/dist/;
+location /static/ {
+    alias /var/www/app/static/;
     access_log off;
     expires 1y;
     add_header Cache-Control "public, immutable";
@@ -159,7 +161,7 @@ Each release is deployable on its own. Each rollback goes to a compatible previo
 - **DB backups** — Postgres point-in-time recovery via WAL archiving. Standard RDS / Cloud SQL options cover this.
 - **Secrets** — `SM_SECRET_KEY` must be recoverable from your secrets manager. Rotating it invalidates all sessions but doesn't break anything else.
 - **Sessions** — lost sessions mean users re-login; acceptable.
-- **Uploads** — the `file_storage` module's `local` backend is ephemeral. For production, point it at S3 or a network filesystem and back that up independently.
+- **Uploads** — the `file_storage` module's `filesystem` backend is ephemeral. For production, point it at S3 or a network filesystem and back that up independently.
 
 ## Publishing releases
 
diff --git a/docs/reference/diagnostic-codes.md b/docs/reference/diagnostic-codes.md
index 9317d5b6..36515438 100644
--- a/docs/reference/diagnostic-codes.md
+++ b/docs/reference/diagnostic-codes.md
@@ -1,6 +1,6 @@
 # Diagnostic codes
 
-The framework runs a set of static checks over installed modules at app boot. Errors fail boot in production (`SM_ENVIRONMENT` ≠ `development`/`test`/`testing`); warnings print to stderr in dev and are ignored in prod.
+The framework runs a set of static checks over installed modules at app boot. The full structural/page/i18n suite runs in development (`SM_ENVIRONMENT=development`), prints to stderr, and aborts boot on any ERROR. In non-development environments (anything other than `development`) module discovery is **strict** — entry-point failures and missing/invalid `meta` (the SM001 class of problems) raise at boot — and the migration check (SM010) fails boot in every environment.
 
 ## Levels
 
@@ -16,9 +16,9 @@ The framework runs a set of static checks over installed modules at app boot. Er
 | `SM003` | WARNING | `pages/<name>.tsx` exists but no `inertia.render()` call in any module references the corresponding page key. | Remove the orphan file, or add the matching `inertia.render("<Module>/<name>", ...)` in `views.py`. |
 | `SM004` | WARNING | An `inertia.render("<Module>/<name>")` call exists but no matching `.tsx` file is shipped. | Create `pages/<name>.tsx`, or correct the render key. |
 | `SM007` | INFO | Module overrides zero `register_*` hooks and has no `on_startup`/`on_shutdown`. | Delete the module if it's vestigial; otherwise ignore. |
-| `SM008` | ERROR | Two modules declare the same `ModuleMeta.name`. Schema / prefix collision. | Rename one. Remember: name is used as Postgres schema, SQLite table prefix, Inertia namespace. |
+| `SM008` | ERROR | Two modules declare the same `ModuleMeta.name`. Table-prefix collision. | Rename one. Remember: the name is the table-name prefix (all modules share one DB schema) and the Inertia namespace. |
 | `SM009` | ERROR | A file under `framework/*` imports from any package under `modules/*`. | Invert the dependency: have the module register a callback into the framework (see `principal_serializer` pattern). |
-| `SM010` | ERROR | DB `alembic_version` is behind the migration head. | Run `make migrate`. In dev this prints a warning; in production it's a hard failure before serving. |
+| `SM010` | ERROR | DB `alembic_version` is behind the migration head. | Run `make migrate`. The lifespan migration check raises and aborts boot in every environment before serving. |
 | `SM011` | WARNING | A module's model declares a table that doesn't appear in any Alembic migration. | Run `uv run alembic revision --autogenerate -m "..."`, review, `make migrate`. |
 | `SM012` | WARNING | Module overrides `register_settings` but does not assign to `app.state.<module_lower>`. Dev-only. | Either remove the override or move your state assignment into it. |
 | `SM013` | WARNING | Supported locale has no corresponding file in some module's `locales/`. | Add `modules/<name>/<name>/locales/<locale>.json`, or drop the locale from `SM_I18N_SUPPORTED_LOCALES`. |
@@ -28,13 +28,15 @@ The framework runs a set of static checks over installed modules at app boot. Er
 | `SM017` | WARNING | Module ships `.tsx` pages but has no `package.json` / `tsconfig.json`. Vite can't resolve type imports. | Run `smpy create-module` on a dummy name and copy the generated config, or scaffold by hand. |
 | `SM018` | WARNING | An Inertia `router.post/patch/put/delete()` call in a page targets a JSON `/api/*` endpoint, which would return raw JSON and be rejected by Inertia. | Point the call at a view endpoint that returns `inertia.render(...)` or a redirect; or use plain `fetch()` if you really want a JSON response. |
 | `SM019` | WARNING | Module declares a non-empty `view_prefix` and overrides `register_routes` but registers neither menu items nor permissions — admins can't reach the pages from the sidebar or grant access from the role editor. | Add `register_menu_items` for a sidebar entry, or `register_permissions` to surface the module in the role editor (sub-pages of another module typically just register permissions). |
+| `SM020` | ERROR | More than one auth-provider module is installed (e.g. both `users` and `keycloak`). | Install exactly one auth provider. |
+| `SM021` | WARNING | No auth-provider module is installed. | Install an auth provider (e.g. `simple-module-users` or `simple-module-keycloak`). |
 
 ## When diagnostics fire
 
 | Context | What runs |
 |---|---|
-| App boot in development | Full suite, results logged to stderr. Doesn't abort. |
-| App boot in production | Full suite. ERRORS abort boot before serving. |
+| App boot in development | Full structural/page/i18n suite, results logged to stderr. ERRORS abort boot. |
+| App boot in non-development | Strict module discovery (raises on SM001-class failures) + the migration check (SM010). The page/locale static suite is dev-only. |
 
 Sample dev-mode output:
 
@@ -55,6 +57,6 @@ Treat a clean dev boot as the "ready to ship" gate. If you want to run the diagn
 If you think a rule deserves a code, open a design doc in `docs/plans/` first — existing codes are stable contracts (downstream tooling can grep for them). Use the next free number in the `SM0XX` range and:
 
 1. Add the check to `simple_module_core.diagnostics`.
-2. Wire it into `build_diagnostics_pass()` so it runs at app boot.
+2. Wire it into `run_diagnostics()` (or the relevant `*Diagnostics.run()` method) so it runs at app boot.
 3. Update this page with the row.
-4. Add a test case under `tests/framework/core/diagnostics/`.
+4. Add a test case under `framework/core/tests/`.
diff --git a/docs/reference/env-vars.md b/docs/reference/env-vars.md
index e2360b64..16d1061f 100644
--- a/docs/reference/env-vars.md
+++ b/docs/reference/env-vars.md
@@ -9,68 +9,70 @@ This is the full reference. See [Configuration](/guide/configuration) for a narr
 | Variable | Default | Notes |
 |---|---|---|
 | `SM_DATABASE_URL` | `sqlite+aiosqlite:///./app.db` | **Required in production.** Async URL: `postgresql+asyncpg://user:pw@host:5432/db` or `sqlite+aiosqlite:///./app.db`. |
-| `SM_ENVIRONMENT` | `development` | Any value other than `development`, `test`, `testing` triggers strict discovery + placeholder-secret checks. |
+| `SM_ENVIRONMENT` | `development` | `development` and `testing` are the only non-prod values (placeholder-secret check is skipped for both). Any value other than `development` triggers strict module discovery. |
 | `SM_SECRET_KEY` | `change-me-in-production` | **Must** be overridden in production — session cookie signing key. |
 | `SM_DEBUG` | `false` | Enables debug mode (tracebacks in HTTP responses). |
 | `SM_LOG_LEVEL` | `INFO` | `DEBUG`/`INFO`/`WARNING`/`ERROR`. |
-| `SM_LOG_FORMAT` | `plain` | `plain` for dev, `json` for structured logs in prod. |
-| `SM_MULTI_TENANT` | `false` | Enables `TenantMiddleware` + `MultiTenantMixin` auto-filter. |
-| `SM_TENANT_HEADER` | `X-Tenant-ID` | HTTP header that identifies the current tenant. |
+| `SM_LOG_FORMAT` | `json` | `text` for readable dev logs, `json` for structured logs in prod. |
 | `SM_MODULES_ENABLED` | unset | Comma-separated allow-list to disable modules without uninstalling them. |
 | `SM_VITE_DEV_URL` | `http://localhost:5050` | Dev only — where the Vite HMR client connects. |
+| `SM_AUTH_PUBLIC_PATHS` | `[]` | JSON array of host-level anonymous-access path prefixes. Escape hatch for exposing a route without a session when no module owns it; modules should prefer the method-aware `register_public_routes` hook. |
 
 ## DB connection pool
 
 | Variable | Default | Notes |
 |---|---|---|
-| `SM_DB_POOL_SIZE` | `5` | SQLAlchemy `pool_size`. |
-| `SM_DB_MAX_OVERFLOW` | `10` | SQLAlchemy `max_overflow`. |
+| `SM_DB_POOL_SIZE` | `10` | SQLAlchemy `pool_size`. |
+| `SM_DB_MAX_OVERFLOW` | `20` | SQLAlchemy `max_overflow`. |
 | `SM_DB_POOL_PRE_PING` | `true` | Test connections before use. |
 | `SM_DB_POOL_RECYCLE` | `1800` | Recycle connections after N seconds (helps with LB idle drops). |
 
-## Internationalization
+## Host settings (DB-backed, not env)
 
-| Variable | Default | Notes |
+Multi-tenancy and i18n configuration live in the DB-backed host settings store (`HostSettings`, registered under `package="host"`), **not** in env vars. Edit them in the admin UI at `/settings/modules` under the host section. Their defaults:
+
+| Setting | Default | Notes |
 |---|---|---|
-| `SM_I18N_DEFAULT_LOCALE` | `en` | Must be in `SM_I18N_SUPPORTED_LOCALES`. |
-| `SM_I18N_SUPPORTED_LOCALES` | `en` | Comma-separated, e.g. `en,es,de`. |
-| `SM_I18N_COOKIE_NAME` | `locale` | Cookie that stores the user's selected locale. |
+| `multi_tenant` | `false` | Enables `TenantMiddleware` + `MultiTenantMixin` auto-filter. |
+| `tenant_header` | `""` | HTTP header that identifies the current tenant (empty = tenant middleware disabled). |
+| `i18n_default_locale` | `en` | Must be in `i18n_supported_locales`. |
+| `i18n_supported_locales` | `["en"]` | e.g. `["en", "es", "de"]`. |
+| `i18n_cookie_name` | `locale` | Cookie that stores the user's selected locale. |
 
 ## Users module
 
+Most users settings (signup, mailer, SMTP, OAuth/OIDC credentials, rate limits) are now **DB-backed** — edit them in the admin UI at `/settings/modules` under Users, not via env vars. The env vars below are the genuine bootstrap-time exceptions read at process start.
+
 | Variable | Default | Notes |
 |---|---|---|
-| `SM_USERS_BOOTSTRAP_EMAIL` | unset | Auto-creates an admin if set **and** `users_user` is empty. |
+| `SM_USERS_BOOTSTRAP_EMAIL` | unset | Auto-creates an admin if set **and** the users table is empty. |
 | `SM_USERS_BOOTSTRAP_PASSWORD` | unset | Paired with the email above. |
-| `SM_USERS_ALLOW_SIGNUP` | `false` | If `true`, `/users/register` is public. |
-| `SM_USERS_MAILER` | `console` | `console` logs the invite link to stdout; `smtp` sends real emails. |
-| `SM_USERS_BASE_URL` | derived | Public URL used to build invite links. |
-| `SM_USERS_SMTP_HOST` | — | Required when mailer is `smtp`. |
-| `SM_USERS_SMTP_PORT` | `587` | |
-| `SM_USERS_SMTP_USERNAME` | — | |
-| `SM_USERS_SMTP_PASSWORD` | — | |
-| `SM_USERS_SMTP_FROM` | — | |
-| `SM_USERS_SMTP_TLS` | `true` | |
+| `SM_USERS_BOOTSTRAP_USER_EMAIL` | unset | Optional second non-admin seed user (handy in dev). |
+| `SM_USERS_BOOTSTRAP_USER_PASSWORD` | unset | Paired with the user email above. |
+| `SM_USERS_RESET_PASSWORD_TOKEN_SECRET` | dev placeholder | HMAC key for password-reset tokens. **Must** be overridden in production (boot fails otherwise). |
+| `SM_USERS_VERIFICATION_TOKEN_SECRET` | dev placeholder | HMAC key for email-verification tokens. **Must** be overridden in production (boot fails otherwise). |
 
 ## Background tasks (Celery)
 
-Prefix `SM_BG_TASKS_*`. Set in `docker-compose.yml` for local dev.
+Celery config (`broker_url`, `result_backend`, queue, retention, etc.) is now **DB-backed** — edit it in the admin UI at `/settings/modules` under BackgroundTasks. Defaults are `redis://localhost:6379/0` (broker) and `/1` (result backend). Because workers read the broker/backend once at process start, changing those values requires a worker restart.
+
+The one field still read from the environment at import time:
 
 | Variable | Default | Notes |
 |---|---|---|
-| `SM_BG_TASKS_BROKER_URL` | `redis://localhost:6379/0` | Celery broker. |
-| `SM_BG_TASKS_RESULT_BACKEND` | `redis://localhost:6379/1` | Celery result backend. |
+| `SM_BG_TASKS_TASK_ALWAYS_EAGER` | `false` | Run tasks synchronously in the calling process (used by tests). |
 
 ## File storage module
 
-| Variable | Default | Notes |
-|---|---|---|
-| `SM_FILE_STORAGE_BACKEND` | `local` | `local`, `s3`, or `memory`. |
-| `SM_FILE_STORAGE_LOCAL_ROOT` | `./storage` | Local backend root directory. |
-| `SM_FILE_STORAGE_S3_BUCKET` | — | S3 bucket name. |
-| `SM_FILE_STORAGE_S3_REGION` | — | S3 region. |
+File storage config is now **DB-backed** — edit it in the admin UI at `/settings/modules` under Files. The key fields and defaults:
 
-Most of the storage config moved to DB-backed settings; the env vars above are the ones needed at bootstrap.
+| Setting | Default | Notes |
+|---|---|---|
+| `backend` | `filesystem` | `filesystem` or `s3` (S3-compatible: AWS S3, MinIO, R2). |
+| `fs_root_path` | `./uploads` | Filesystem backend root directory. |
+| `s3_bucket` | `""` | S3 bucket name (required when backend is `s3`). |
+| `s3_region` | `""` | S3 region (required when backend is `s3`). |
+| `s3_endpoint_url` | `""` | Custom endpoint for MinIO / R2; blank uses AWS default. |
 
 ## Patterns
 
@@ -80,7 +82,7 @@ Every module-owned env var uses `SM_<MODULE_UPPER>_*`. Keeps settings self-descr
 
 ### Comma-separated lists
 
-Pydantic parses comma-separated strings into `list[str]` — `SM_I18N_SUPPORTED_LOCALES=en,es,de` becomes `["en", "es", "de"]`.
+Pydantic parses comma-separated strings into `list[str]` — `SM_MODULES_ENABLED=users,dashboard` becomes `["users", "dashboard"]`. (`SM_AUTH_PUBLIC_PATHS` is the exception — it takes a JSON array, e.g. `["/status", "/api/webhook"]`.)
 
 ### Booleans
 
@@ -88,7 +90,7 @@ Pydantic parses comma-separated strings into `list[str]` — `SM_I18N_SUPPORTED_
 
 ### Placeholder-secret check
 
-In production (`SM_ENVIRONMENT != development`), boot fails if `SM_SECRET_KEY == "change-me-in-production"`. Override before deploying.
+In production (`SM_ENVIRONMENT` not in `{development, testing}`), boot fails if `SM_SECRET_KEY == "change-me-in-production"`. Override before deploying.
 
 ### `.env` files
 
diff --git a/docs/release.md b/docs/release.md
index 9821d9df..526d4953 100644
--- a/docs/release.md
+++ b/docs/release.md
@@ -4,7 +4,7 @@ This repo publishes **13 Python packages** to PyPI and **3 JS packages** to npm
 
 - **Python packages** (`simple_module_*`) → [pypi.org](https://pypi.org)
 - **JS packages** (`@simple-module-py/*`) → [npmjs.com](https://www.npmjs.com)
-- **Auth**: OIDC Trusted Publishing on PyPI; `NPM_TOKEN` on npm
+- **Auth**: OIDC Trusted Publishing on both PyPI and npm — no long-lived tokens
 - **Entry point**: Actions → `release` → Run workflow
 
 ## TL;DR — already set up? Cut a release in 3 clicks
@@ -23,7 +23,7 @@ You need to set up Trusted Publisher entries on PyPI and npm *before* running th
 
 ### 1. PyPI
 
-For *each* of the 13 Python project names, on [pypi.org](https://pypi.org/manage/account/publishing/):
+For *each* of the 13 published Python project names, on [pypi.org](https://pypi.org/manage/account/publishing/):
 
 1. Log in as the owner account (`antosubash`).
 2. Go to **Your account → Publishing** (or click "Add a new pending publisher" if the project doesn't exist yet).
@@ -38,6 +38,7 @@ For *each* of the 13 Python project names, on [pypi.org](https://pypi.org/manage
 Repeat for every project in this list:
 
 ```
+simple_module_cli
 simple_module_core
 simple_module_db
 simple_module_hosting
@@ -52,14 +53,25 @@ simple_module_settings
 simple_module_users
 ```
 
+(`simple_module_audit_log` and `simple_module_keycloak` live in the workspace and
+get version-bumped, but are **not** in the `publish-pypi` matrix — they are not
+published to PyPI.)
+
 > **Pending publishers**: if a project doesn't exist on PyPI yet, "pending publisher" is the right flow — you're reserving the project name *and* wiring up auth in one step. The first successful publish creates the project and promotes the pending publisher to a real one.
 
 ### 2. npm
 
-1. On [npmjs.com](https://www.npmjs.com), sign in as the owner.
+npm publishes also use OIDC Trusted Publishing (no `NPM_TOKEN` secret). On
+[npmjs.com](https://www.npmjs.com):
+
+1. Sign in as the owner.
 2. Create the `@simple-module-py` organization (Settings → "Create a new organization"). This is a one-time step.
-3. Generate an automation-type access token with publish rights for `@simple-module-py/*`.
-4. In this repo: **Settings → Secrets and variables → Actions → New repository secret**, name `NPM_TOKEN`, paste the token.
+3. For *each* of the 3 npm packages (`@simple-module-py/ui`, `/i18n`, `/tsconfig`), open the package's **Settings → Trusted Publisher** page and add a GitHub Actions publisher:
+   - **Repository**: `antosubash/simple_module_python`
+   - **Workflow filename**: `release.yml`
+   - **Environment**: `npm`
+
+   For a brand-new scoped package that doesn't exist yet, create it with an initial manual `npm publish` (or reserve it) before the Trusted Publisher entry can be attached.
 
 ### 3. GitHub Environments
 
@@ -68,7 +80,7 @@ In the repo's **Settings → Environments → New environment**, create two envi
 - `pypi`
 - `npm`
 
-No secrets or variables are needed on the `pypi` environment (OIDC). Optionally, add a **deployment-protection rule** requiring a manual approval on both so every release gets a human click before it goes live.
+No secrets or variables are needed on either environment — both publish via OIDC. Optionally, add a **deployment-protection rule** requiring a manual approval on both so every release gets a human click before it goes live.
 
 ### 4. Branch protection
 
@@ -92,7 +104,7 @@ Both should pass locally. CI should be green on every PR into `main`.
 
 ### Step 2. Pick a version
 
-All 16 packages bump in lockstep to the same version. We follow a relaxed SemVer during the 0.x phase:
+Every workspace package bumps in lockstep to the same version — `scripts/bump_version.py` walks every `framework/*`, `modules/*`, and `packages/*` manifest (so the two unpublished modules, `audit_log` and `keycloak`, stay in sync too). Only the 13 PyPI + 3 npm packages are then published. We follow a relaxed SemVer during the 0.x phase:
 
 | Situation | Input |
 |---|---|
@@ -112,9 +124,9 @@ The workflow derives the next version from the current `framework/core/pyproject
 
 What happens:
 - `resolve` computes the final version and shares it with every downstream job.
-- `build` rewrites every version, builds 13 wheels + 13 sdists + 3 npm tarballs, and uploads them as artifacts.
-- `publish-pypi` fans out 13 parallel jobs, each publishing one wheel+sdist pair via OIDC Trusted Publishing.
-- `publish-npm` fans out 3 parallel jobs publishing `@simple-module-py/*` tarballs with `NPM_TOKEN`. Each job verifies the tarball's `package.json` is actually scoped to `@simple-module-py/*` before invoking `npm publish`.
+- `build` rewrites every version, runs `uv build --all-packages` (a wheel + sdist for every buildable workspace package) plus the 3 npm tarballs, and uploads them as artifacts.
+- `publish-pypi` fans out 13 parallel jobs (the matrix package list), each filtering the artifact set down to one package and publishing its wheel+sdist pair via OIDC Trusted Publishing.
+- `publish-npm` fans out 3 parallel jobs publishing `@simple-module-py/*` tarballs via OIDC Trusted Publishing. Each job verifies the tarball's `package.json` is actually scoped to `@simple-module-py/*` before invoking `npm publish`.
 - `finalize` re-applies the bump, commits `release: vX.Y.Z`, tags it, and pushes both.
 
 Expected wall time: 5–8 minutes.
@@ -137,7 +149,7 @@ gh release edit vX.Y.Z --notes-file - < notes.md
 Before running the workflow, you can rehearse the whole pipeline offline. Nothing leaves your machine:
 
 ```bash
-# 1. Check all 16 packages are currently at 0.0.1 (or your expected base)
+# 1. Check every workspace package is currently at 0.0.1 (or your expected base)
 uv run python scripts/bump_version.py 0.0.1 --check
 
 # 2. Dry-run the bump (writes nothing, shows what would change)
@@ -157,7 +169,7 @@ uv build --all-packages --out-dir dist-py
 mkdir -p dist-npm && for p in packages/*/; do npm pack "$p" --pack-destination dist-npm; done
 
 # 6. Sanity-check contents
-ls dist-py/ | wc -l        # expect 26 (13 wheels + 13 sdists)
+ls dist-py/ | wc -l        # expect 30 (a wheel + sdist for each of the 15 buildable packages; only 13 are later published)
 ls dist-npm/ | wc -l       # expect 3
 
 # 7. Revert (if you don't actually want to release)
@@ -179,9 +191,9 @@ The PyPI project's Trusted Publisher entry is missing or mismatched. Common caus
 
 Fix the entry on the registry, re-run the failed job.
 
-### npm publish fails with `401 Unauthorized` or a weird git error
+### npm publish fails with `401`/`403` or a weird git error
 
-- `401` → `NPM_TOKEN` secret is missing, expired, or lacks publish rights on `@simple-module-py/*`. Rotate and re-run.
+- `401`/`403` → the package's npm **Trusted Publisher** entry is missing or mismatched (wrong repo, workflow filename, or environment), or the `npm` GitHub environment / `id-token: write` permission isn't wired up. Fix the entry on npm and re-run. (npm publishes via OIDC now — there is no `NPM_TOKEN` secret to rotate.)
 - `git ls-remote` / `Permission denied (publickey)` → npm is mis-parsing the tarball path. This is guarded for in the workflow (the path is prefixed with `./` and the package name is verified against `@simple-module-py/<pkg>`). If you see it again, the guard has regressed.
 
 ### `git push` fails in "Commit, tag, push" step
@@ -199,8 +211,8 @@ PyPI is immutable — you cannot re-upload `0.0.2` under any circumstance. Optio
 
 ### A new module was added — how do I include it in releases?
 
-1. Add its distribution name to `scripts/bump_version.py`'s package list (should be automatic if it lives under `modules/*/pyproject.toml`).
-2. Add it to `.github/workflows/release.yml` under `publish-pypi` → `strategy.matrix.package`.
+1. Version-bumping is automatic — `scripts/bump_version.py` discovers any `modules/*/pyproject.toml`, so a new module is picked up with no edit.
+2. Add it to `.github/workflows/release.yml` under `publish-pypi` → `strategy.matrix.package` (only matrix packages are published; that's how `audit_log`/`keycloak` stay unpublished).
 3. Create the PyPI Trusted Publisher entry for its project name.
 4. Add a substantive README (`check_readmes.py` will fail otherwise).
 
@@ -208,7 +220,7 @@ PyPI is immutable — you cannot re-upload `0.0.2` under any circumstance. Optio
 
 ### I need to rotate or recover the owner account
 
-Trusted Publishing is tied to the GitHub repo, not any personal account — so a PyPI account handover is the usual account-transfer flow at the registry, not a code change. For npm, rotate `NPM_TOKEN` under the new owner. Update the "Project names" section of this doc afterward.
+Trusted Publishing is tied to the GitHub repo, not any personal account — so both PyPI and npm account handovers are the usual account-transfer flow at each registry, not a code change. The Trusted Publisher entries stay valid as long as the repo, workflow filename, and environment names are unchanged. Update the "Project names" section of this doc afterward.
 
 ---
 
@@ -216,9 +228,10 @@ Trusted Publishing is tied to the GitHub repo, not any personal account — so a
 
 | Registry | Package | Source |
 |---|---|---|
+| PyPI | `simple_module_cli` | [framework/cli/](../framework/cli/) — ships the `smpy` / `simple-module` CLI |
 | PyPI | `simple_module_core` | [framework/core/](../framework/core/) |
 | PyPI | `simple_module_db` | [framework/db/](../framework/db/) |
-| PyPI | `simple_module_hosting` | [framework/hosting/](../framework/hosting/) — ships the `sm` / `simple-module` CLI |
+| PyPI | `simple_module_hosting` | [framework/hosting/](../framework/hosting/) — ships the `sm-host` CLI |
 | PyPI | `simple_module_test` | [framework/testing/](../framework/testing/) — pytest plugin |
 | PyPI | `simple_module_auth` | [modules/auth/](../modules/auth/) |
 | PyPI | `simple_module_background_tasks` | [modules/background_tasks/](../modules/background_tasks/) |
diff --git a/docs/testing/fixtures.md b/docs/testing/fixtures.md
index 560cbcb3..d939a1f1 100644
--- a/docs/testing/fixtures.md
+++ b/docs/testing/fixtures.md
@@ -28,7 +28,7 @@ def test_settings_defaults(settings):
 
 ## `db_session`
 
-The workhorse. Creates a fresh in-memory DB, runs `CREATE TABLE` for every module's tables (via `build_module_metadata()`), stamps `alembic_version` at head, and yields an `AsyncSession`.
+The workhorse. Creates a fresh in-memory DB, runs `CREATE TABLE` for every module's tables (iterating `all_module_bases` and calling `base.metadata.create_all`), stamps `alembic_version` at head, and yields an `AsyncSession`.
 
 ```python
 from decimal import Decimal
@@ -121,7 +121,7 @@ async def test_non_admin_denied(client, db_session):
 
 ## Fixture composition
 
-Fixtures compose the expected way — `client` depends on `app`, which depends on `db_session`, which depends on `db_state`, which depends on `settings`. Request only the fixture you need; the DAG pulls in the rest.
+Fixtures compose the expected way — `client` and `authenticated_client` depend on `app`, which depends on `settings` (and creates its own tables on `app.state.sm.db.engine`). The `db_session` / `engine` fixtures depend on `db_state`, which builds its own in-memory engine independent of `settings`. Request only the fixture you need; the DAG pulls in the rest.
 
 Adding your own fixtures at module level:
 
diff --git a/docs/testing/overview.md b/docs/testing/overview.md
index 98d83822..9e3f81e5 100644
--- a/docs/testing/overview.md
+++ b/docs/testing/overview.md
@@ -6,7 +6,7 @@ The framework expects three kinds of tests:
 - **Integration tests** — endpoints via `client` / `authenticated_client`. Still `pytest`.
 - **E2E tests** — Playwright-driven browser tests marked `e2e`, excluded from default runs.
 
-The default `pytest` invocation pins `-m 'not e2e'` (your app's `pyproject.toml`), so a normal test run never touches the Playwright suite — run those explicitly via `uv run pytest -m e2e tests/e2e`.
+The default `pytest` invocation pins `-m 'not e2e and not perf'` (your app's `pyproject.toml`), so a normal test run never touches the Playwright suite or the benchmarks — run e2e explicitly via `uv run pytest -m e2e tests/e2e`.
 
 ## Quick reference
 
@@ -19,8 +19,8 @@ The default `pytest` invocation pins `-m 'not e2e'` (your app's `pyproject.toml`
 | `uv run pytest -x` | Stop at first failure. |
 | `uv run pytest -v -s` | Verbose + capture off (see `print`). |
 | `uv run pytest -m e2e tests/e2e` | Playwright suite against `localhost:8000`. Requires `make dev` running. |
-| `cd client_app && npx vitest run` | Run every JS test. |
-| `cd client_app && npx vitest run <path>` | Single JS test file. |
+| `npm test` (or `npx vitest run`) | Run every JS test (from the repo root). |
+| `npx vitest run <path>` | Single JS test file. |
 
 ## Async mode
 
@@ -30,17 +30,16 @@ The root `pyproject.toml` sets `asyncio_mode = "auto"`. Async tests don't need `
 
 ```text
 conftest.py                    # root fixtures: app, db_session, client, authenticated_client
+framework/<pkg>/tests/         # tests against each framework package (core, db, hosting, cli, testing)
+host/tests/                    # host-level tests
+modules/<name>/tests/          # per-module pytest tests
 tests/
-├── framework/                 # tests against framework/ packages
-│   ├── core/
-│   ├── db/
-│   └── hosting/
-├── modules/                   # tests that live at the root, cross-module
+├── integration/               # cross-module integration tests
+├── benchmarks/                # perf benchmarks (marked `perf`)
 └── e2e/                       # Playwright tests (marked `e2e`)
-modules/<name>/tests/          # per-module pytest tests
 ```
 
-Any `conftest.py` under a subtree can add more fixtures; they cascade down but don't leak sideways. Keep module-specific fixtures in the module's `tests/conftest.py`.
+These directories are enumerated in `testpaths` in the root `pyproject.toml`. Any `conftest.py` under a subtree can add more fixtures; they cascade down but don't leak sideways. Keep module-specific fixtures in the module's `tests/conftest.py`.
 
 ## What good tests look like
 
@@ -60,14 +59,14 @@ There's no enforced coverage percentage, but:
 
 ## JS / TSX tests
 
-Vitest + Testing Library, configured in `vitest.config.ts` and `vitest.setup.ts`. Tests live next to the source:
+Vitest + Testing Library, configured in the repo-root `vitest.config.ts` and `vitest.setup.ts`. The config's `include` globs cover `packages/**` and `host/client_app/**`, so tests live next to the source there:
 
 ```text
-modules/orders/orders/pages/__tests__/Browse.test.tsx
-packages/ui/src/components/__tests__/Button.test.tsx
+packages/ui/src/components/StatCard.test.tsx
+host/client_app/<something>.test.tsx
 ```
 
-Run all: `npx vitest run`. Watch: `npx vitest`. Single file: `npx vitest run path/to/Browse.test.tsx`.
+Run all: `npm test` (or `npx vitest run`). Watch: `npx vitest`. Single file: `npx vitest run path/to/StatCard.test.tsx`.
 
 Use `@testing-library/react`'s `render` and query helpers:
 
@@ -81,7 +80,7 @@ it("shows the empty state", () => {
 });
 ```
 
-For pages that depend on `useT` / `useAuth`, wrap in a mock provider from `packages/ui/src/test-utils.tsx`.
+For components that depend on `useT` / `usePage`, mock the source module with `vi.mock("@simple-module-py/i18n", ...)` / `vi.mock("@inertiajs/react", ...)` — see `packages/ui/src/components/LocaleSwitcher.test.tsx`.
 
 ## Flaky-test checklist
 
diff --git a/framework/cli/README.md b/framework/cli/README.md
index 3147002d..b904565b 100644
--- a/framework/cli/README.md
+++ b/framework/cli/README.md
@@ -23,7 +23,7 @@ smpy create-module my_feature         # scaffold a publishable module package
 smpy create-host bare-host            # scaffold a bare host (no opinionated wiring)
 ```
 
-Built-in commands: `smpy new`, `smpy create-host`, `smpy create-module`.
+Built-in commands: `smpy new`, `smpy create-host`, `smpy create-module`, `smpy package-update`, and `smpy skills {list,add,update}`.
 
 When other framework packages are installed, they contribute additional subcommands via the `simple_module_cli.cli_plugins` entry-point group:
 
diff --git a/framework/core/README.md b/framework/core/README.md
index 57747899..52574ed0 100644
--- a/framework/core/README.md
+++ b/framework/core/README.md
@@ -2,7 +2,7 @@
 
 Module-system primitives for the [simple_module](https://github.com/antosubash/simple_module_python) framework — a modular-monolith for Python/FastAPI where each feature is a plugin package discovered at boot.
 
-This package defines `ModuleBase`, the `ModuleMeta` descriptor, the `discover_modules()` entry-point loader, topological dependency sorting, event bus primitives, and the diagnostic codes (`SM001`–`SM017`) used by `make doctor`.
+This package defines `ModuleBase`, the `ModuleMeta` descriptor, the `discover_modules()` entry-point loader, topological dependency sorting, event bus primitives, and the diagnostic codes (`SM001`–`SM021`) used by `make doctor`.
 
 ## Install
 
@@ -17,7 +17,7 @@ You usually don't install this directly — it's pulled in by `simple_module_hos
 - `ModuleBase` — the subclass every module extends to opt into lifecycle hooks.
 - `ModuleMeta` — required `meta = ModuleMeta(name=..., depends_on=...)` attribute on each module.
 - `discover_modules()` — loads all `[project.entry-points.simple_module]` modules, topologically sorts by `depends_on`.
-- Diagnostic registry — `SM001` missing meta, `SM003` orphan page, `SM008` duplicate name, `SM009` framework→plugin coupling violation, and ~ten others.
+- Diagnostic registry — `SM001` missing meta, `SM003` orphan page, `SM008` duplicate name, `SM009` framework→plugin coupling violation, and the rest of the `SM0xx` set through `SM021`.
 - Tiny event-bus (`pyee`) for decoupled module-to-module communication.
 
 ## Usage
diff --git a/modules/audit_log/README.md b/modules/audit_log/README.md
index 4b8132ce..e573be54 100644
--- a/modules/audit_log/README.md
+++ b/modules/audit_log/README.md
@@ -1,6 +1,6 @@
 # simple_module_audit_log
 
-Automatic field-level audit trail for all SQLModel entities in [simple_module](https://github.com/antosubash/simple_module_python) apps. Every create / update / delete / soft-delete is captured in `audit_log.audit_entries` with the changed fields, the user who made the change, and the request correlation id — no instrumentation required in module code.
+Automatic field-level audit trail for all SQLModel entities in [simple_module](https://github.com/antosubash/simple_module_python) apps. Every create / update / delete / soft-delete is captured in the `audit_log_audit_entry` table with the changed fields, the user who made the change, and the request correlation id — no instrumentation required in module code.
 
 ## Install
 
diff --git a/modules/auth/README.md b/modules/auth/README.md
index a589683e..6ee91244 100644
--- a/modules/auth/README.md
+++ b/modules/auth/README.md
@@ -1,8 +1,8 @@
 # simple_module_auth
 
-Session-cookie authentication primitives for [simple_module](https://github.com/antosubash/simple_module_python) apps. Provides the `SessionMiddleware` wiring, login/logout helpers, and login-redirect handling used by the `simple_module_users` module.
+Pluggable authentication core for [simple_module](https://github.com/antosubash/simple_module_python) apps. Owns the stable public contracts every other module imports — `UserContext`, the `AuthProvider` protocol, the `PrincipalResolver` chain, and the `get_current_user` / `CurrentUser` / `require_permission` dependencies — plus the `AuthMiddleware` that resolves the current principal on every request.
 
-**Heads up:** for most apps you don't install this directly — `simple_module_users` pulls it in and builds the email+password auth flow on top of these primitives.
+**Heads up:** for most apps you don't install this directly — an auth-provider module (`simple_module_users` for email+password, `simple_module_keycloak` for OIDC) pulls it in and registers itself on `app.state.auth.auth_provider`.
 
 ## Install
 
@@ -12,26 +12,39 @@ pip install simple_module_auth
 
 ## What it provides
 
-- Starlette `SessionMiddleware` configuration reading `SM_SECRET_KEY` and `SM_SESSION_COOKIE_*` env vars.
-- `current_user_id` FastAPI dependency reading the signed session cookie.
-- Redirect-to-login helpers for unauthenticated requests on Inertia routes.
-- Login-required decorator / dependency for protecting routes without pulling in the heavier `simple_module_users` package.
+- `UserContext` — the request-scoped principal (`id`, `name`, `email`, `roles`).
+- `AuthProvider` protocol — the swappable-backend contract (`resolve_user`, `get_login_url`, `get_logout_url`, `get_public_paths`, `is_bearer_request`); exactly one provider module registers an implementation on `app.state.auth.auth_provider`.
+- `PrincipalResolver` chain — async `(Request) -> UserContext | None` callables apps append to `app.state.auth.principal_resolvers` (e.g. PAT/bearer-token or API-key auth), consulted after the session path.
+- `AuthMiddleware` — delegates to the provider + resolver chain on every request and populates the request principal.
+- `get_current_user` / `CurrentUser` dependency and the `require_permission(*permissions)` dependency factory.
+- Anonymous-access is declared via the framework's method-aware `register_public_routes` hook (with the `SM_AUTH_PUBLIC_PATHS` host-level escape hatch).
 
 ## Usage
 
 ```python
-from fastapi import APIRouter, Depends
-from simple_module_auth import require_login
+from fastapi import APIRouter
+
+from auth.deps import CurrentUser
 
 router = APIRouter()
 
 
 @router.get("/me")
-async def me(user_id: int = Depends(require_login)):
-    return {"user_id": user_id}
+async def me(user: CurrentUser):
+    return {"user_id": user.id, "email": user.email}
 ```
 
-Routes that need more than just "logged in" (e.g. role/permission checks) should use `simple_module_permissions` instead.
+Routes that need a specific permission use the `require_permission(...)` dependency factory:
+
+```python
+from fastapi import Depends
+
+from auth.deps import require_permission
+
+
+@router.post("/", dependencies=[Depends(require_permission("products.create"))])
+async def create_product(): ...
+```
 
 ## Depends on
 
diff --git a/modules/background_tasks/README.md b/modules/background_tasks/README.md
index 31fd660c..c07cb35e 100644
--- a/modules/background_tasks/README.md
+++ b/modules/background_tasks/README.md
@@ -8,36 +8,33 @@ Celery + Redis background-task module for [simple_module](https://github.com/ant
 pip install simple_module_background_tasks
 ```
 
-Requires a Redis broker — set `SM_CELERY_BROKER_URL` (default `redis://localhost:6379/0`).
+Requires a Redis broker. The broker / result-backend URLs are module settings (`broker_url`, default `redis://localhost:6379/0`; `result_backend`, default `redis://localhost:6379/1`) configured from the DB settings store via the admin UI — they are not read from environment variables at runtime. These fields are `requires_restart` (changing them needs a worker/web restart).
 
 ## What it provides
 
-- `register_background_tasks()` module hook — modules declare tasks here; the registry wires them into the Celery app at boot.
-- Admin UI at `/background-tasks/admin` — list recent runs, retry failed, inspect tracebacks.
-- Shared Celery app accessible via `from background_tasks import celery_app` (import name `background_tasks`, distribution name `simple_module_background_tasks`).
+- Zero-config task discovery — any installed module that ships a `tasks.py` has its tasks autodiscovered (`celery.autodiscover_tasks` imports `<package>.tasks` for every installed module). No per-module registration hook.
+- Admin UI at `/admin/background-tasks` — list recent runs, retry failed, inspect tracebacks (gated by the `background_tasks.view` permission).
+- `build_celery(settings)` factory in `background_tasks.celery_app`, plus `bind_task_context` / `get_log_context` / `install_log_filter` exported from the package root (import name `background_tasks`, distribution name `simple_module_background_tasks`).
 
 ## Usage
 
-Declare a task in a module:
+Declare a task in a module's `tasks.py` with Celery's `@shared_task` — it's autodiscovered, no registration hook needed:
 
 ```python
 # modules/reports/reports/tasks.py
-from background_tasks import celery_app   # type: ignore[import-not-found]
+from celery import shared_task
 
 
-@celery_app.task(name="reports.generate")
+@shared_task(name="reports.generate")
 def generate_report(report_id: int) -> None:
     ...
 ```
 
-Register it:
+Declaring `background_tasks` as a `depends_on` ensures the Celery app is built before your tasks run:
 
 ```python
 class ReportsModule(ModuleBase):
     meta = ModuleMeta(name="reports", depends_on=["background_tasks"])
-
-    def register_background_tasks(self):
-        from . import tasks  # noqa: F401 — side-effect: registers tasks
 ```
 
 Enqueue from an endpoint:
@@ -46,10 +43,11 @@ Enqueue from an endpoint:
 generate_report.delay(report_id=42)
 ```
 
-Run a worker locally:
+Run a worker locally (the scaffolded host ships a `scripts/run_worker.py` that builds the app via `build_celery`):
 
 ```bash
-uv run celery -A background_tasks.celery_app worker --loglevel=info
+uv run celery -A scripts.run_worker:celery worker -l info
+uv run celery -A scripts.run_worker:celery beat   -l info
 ```
 
 ## Worker log context
@@ -69,8 +67,9 @@ domain `job_id` that named a Celery task is the canonical example):
 
 ```python
 from background_tasks import bind_task_context
+from celery import shared_task
 
-@celery_app.task
+@shared_task
 def process_dataset(job_id: int) -> None:
     with bind_task_context(job_id=job_id):
         logger.info("starting ingest")   # now carries job_id too
@@ -81,7 +80,7 @@ same `contextvars` directly via `structlog.contextvars.merge_contextvars`.
 
 ## Depends on
 
-- `simple_module_core`, `simple_module_db`, `simple_module_hosting`
+- `simple_module_core`, `simple_module_db`, `simple_module_hosting`, `simple_module_settings`
 - `celery[redis]>=5.4`, `redis>=5`
 
 ## License
diff --git a/modules/dashboard/README.md b/modules/dashboard/README.md
index 0b7148e4..bac6b1e9 100644
--- a/modules/dashboard/README.md
+++ b/modules/dashboard/README.md
@@ -2,7 +2,7 @@
 
 Admin landing page + sidebar menu host for authenticated users of a [simple_module](https://github.com/antosubash/simple_module_python) app. Renders `/dashboard`, collects menu entries registered by every other installed module, and provides the primary Inertia layout.
 
-Pre-wired into any app scaffolded with `simple-module new`.
+Pre-wired into any app scaffolded with `smpy new`.
 
 ## Install
 
@@ -23,14 +23,14 @@ Install the module in a host, and any other module can register a menu entry:
 ```python
 # modules/orders/orders/module.py
 from simple_module_core import ModuleBase, ModuleMeta
-from simple_module_core.menus import MenuItem
+from simple_module_core.menu import MenuItem, MenuRegistry
 
 
 class OrdersModule(ModuleBase):
     meta = ModuleMeta(name="orders")
 
-    def register_menu_items(self):
-        return [MenuItem(label="Orders", href="/orders", icon="shopping-bag")]
+    def register_menu_items(self, registry: MenuRegistry) -> None:
+        registry.add(MenuItem(label="Orders", url="/orders", icon="shopping-bag"))
 ```
 
 The dashboard sidebar picks it up automatically.
diff --git a/modules/feature_flags/README.md b/modules/feature_flags/README.md
index 29c69c7b..549d5bf4 100644
--- a/modules/feature_flags/README.md
+++ b/modules/feature_flags/README.md
@@ -10,42 +10,43 @@ pip install simple_module_feature_flags
 
 ## What it provides
 
-- `Flag` and `TenantFlagOverride` SQLModel tables.
-- `is_enabled("flag.name", tenant_id=...)` consumer API.
-- Admin UI at `/feature-flags/admin` — toggle flags, add tenant overrides.
-- Cache layer so checking a flag on every request is cheap.
+- Flags are *declared* via the framework `register_feature_flags` hook (`FeatureFlagDefinition(name, default_enabled=...)`); the module persists only *overrides* in the `feature_flags_override` SQLModel table (scoped by `scope` / `scope_id`).
+- `FeatureFlagRegistry.is_enabled("flag.name", tenant_id=...)` consumer API (resolution order: tenant override > system override > declared default).
+- Admin UI at `/feature_flags` — toggle flags, add per-scope overrides.
+- The registry is an in-memory cache hydrated from the DB so checking a flag on every request is cheap.
 
 ## Usage
 
-Gate a route:
+Declare a flag in your module:
 
 ```python
-from feature_flags import is_enabled   # type: ignore[import-not-found]
-from fastapi import APIRouter, Depends, HTTPException
-
-router = APIRouter()
+from simple_module_core.feature_flags import FeatureFlagDefinition, FeatureFlagRegistry
 
 
-@router.get("/new-feature")
-async def new_feature(tenant_id: int = Depends(current_tenant_id)):
-    if not await is_enabled("orders.new_pricing_engine", tenant_id=tenant_id):
-        raise HTTPException(404)
-    return {"rolled_out": True}
+class OrdersModule(ModuleBase):
+    def register_feature_flags(self, registry: FeatureFlagRegistry) -> None:
+        registry.add(FeatureFlagDefinition(name="orders.new_pricing_engine", default_enabled=False))
 ```
 
-Seed a flag in a migration or admin UI:
+Gate a route using the registry dependency:
 
 ```python
-# via migration
-Flag(name="orders.new_pricing_engine", enabled=False)
-```
+from fastapi import APIRouter, HTTPException
 
-Tenant override:
+from feature_flags.deps import FeatureFlagRegistryDep   # type: ignore[import-not-found]
 
-```python
-TenantFlagOverride(tenant_id=7, flag_name="orders.new_pricing_engine", enabled=True)
+router = APIRouter()
+
+
+@router.get("/new-feature")
+async def new_feature(flags: FeatureFlagRegistryDep):
+    if not flags.is_enabled("orders.new_pricing_engine"):
+        raise HTTPException(404)
+    return {"rolled_out": True}
 ```
 
+Overrides (system or per-tenant) are managed through the admin UI at `/feature_flags`.
+
 ## Depends on
 
 - `simple_module_core`, `simple_module_db`, `simple_module_hosting`
diff --git a/modules/file_storage/README.md b/modules/file_storage/README.md
index f759451d..3004e13d 100644
--- a/modules/file_storage/README.md
+++ b/modules/file_storage/README.md
@@ -14,39 +14,34 @@ pip install "simple_module_file_storage[s3]"
 
 ## What it provides
 
-- `POST /api/files` upload endpoint with multipart + metadata.
-- `GET /api/files/{id}` signed-URL or stream download.
-- Pluggable backend via `SM_FILE_STORAGE_BACKEND` (`local` | `s3`).
-- S3 config via `SM_FILE_STORAGE_S3_BUCKET`, `SM_FILE_STORAGE_S3_ENDPOINT` (for R2/MinIO/etc.), `SM_FILE_STORAGE_S3_REGION`.
+- `POST /api/file-storage/upload` multipart upload endpoint.
+- `GET /api/file-storage/files` (paged list), `GET /api/file-storage/files/{file_id}` (metadata), `GET /api/file-storage/files/{file_id}/download` (signed-URL redirect or stream), `DELETE /api/file-storage/files/{file_id}`.
+- Pluggable backend selected by the `backend` setting (`filesystem` default | `s3`); third-party backends can register under any id.
+- Settings (`backend`, `s3_bucket`, `s3_region`, `s3_endpoint_url` for R2/MinIO/etc., `s3_access_key_id`, `s3_secret_access_key`, `s3_presign_ttl_seconds`) are configured from the DB settings store via the admin UI — they are not read from `SM_FILE_STORAGE_*` environment variables at runtime.
 
 ## Usage
 
-From another module:
+From another module, inject the service via its dependency:
 
 ```python
-from file_storage.service import FileStorageService   # type: ignore[import-not-found]
+from fastapi import Depends, File, UploadFile
+
+from file_storage.deps import get_file_storage_service   # type: ignore[import-not-found]
+from file_storage.service import FileStorageService      # type: ignore[import-not-found]
 
 async def attach_receipt(
-    svc: FileStorageService = Depends(FileStorageService),
     upload: UploadFile = File(...),
+    svc: FileStorageService = Depends(get_file_storage_service),
 ):
-    record = await svc.save(upload, folder="receipts/")
-    return {"file_id": record.id, "url": record.url}
+    record = await svc.upload(upload)
+    return {"file_id": record.id}
 ```
 
-Env config (example, S3):
-
-```
-SM_FILE_STORAGE_BACKEND=s3
-SM_FILE_STORAGE_S3_BUCKET=my-app-uploads
-SM_FILE_STORAGE_S3_REGION=us-east-1
-AWS_ACCESS_KEY_ID=...
-AWS_SECRET_ACCESS_KEY=...
-```
+Backend and S3 credentials are configured from the admin UI at **/settings/modules → FileStorage** (DB-backed settings); switch `backend` to `s3` and fill in `s3_bucket`, `s3_region`, `s3_endpoint_url` (for MinIO/R2), `s3_access_key_id`, and `s3_secret_access_key`.
 
 ## Depends on
 
-- `simple_module_core`, `simple_module_db`, `simple_module_hosting`
+- `simple_module_core`, `simple_module_db`, `simple_module_hosting`, `simple_module_settings`
 - `aiofiles`
 - Optional: `aioboto3` (install the `[s3]` extra)
 
diff --git a/modules/keycloak/README.md b/modules/keycloak/README.md
index 44f74d33..63f118f4 100644
--- a/modules/keycloak/README.md
+++ b/modules/keycloak/README.md
@@ -8,7 +8,7 @@ Add to your app's `pyproject.toml` dependencies instead of `simple_module_users`
 
 ```toml
 dependencies = [
-    "simple_module_keycloak==0.0.15",
+    "simple_module_keycloak==0.0.17",
 ]
 ```
 
diff --git a/modules/permissions/README.md b/modules/permissions/README.md
index ee390254..4e5db026 100644
--- a/modules/permissions/README.md
+++ b/modules/permissions/README.md
@@ -2,7 +2,7 @@
 
 Role-based access control (RBAC) for [simple_module](https://github.com/antosubash/simple_module_python) apps. Users get roles, roles carry permissions, and route handlers declare required permissions at the decorator or dependency layer.
 
-Pre-wired into any app scaffolded with `simple-module new`.
+Pre-wired into any app scaffolded with `smpy new`.
 
 ## Install
 
@@ -13,9 +13,9 @@ pip install simple_module_permissions
 ## What it provides
 
 - `Role` and `Permission` SQLModel tables, seeded from module-registered defaults.
-- `@require_permission("orders.read")` route decorator and `HasPermission("...")` dependency.
-- Admin UI at `/permissions/admin` for assigning roles to users.
-- `register_permissions()` hook — every module declares its permission strings at boot, the registry dedupes and persists them.
+- `RequiresPermission("...")` FastAPI dependency that honours both role-based and direct user-level grants (the framework also exposes `require_permission(...)` from `auth.deps`).
+- Admin UI for assigning roles/permissions to users, reached through the users admin area at `/users/admin`; role and user editors live at `/permissions/roles/{id}/edit` and `/permissions/users/{id}/edit`.
+- `register_permissions(self, registry)` hook — every module declares its permission strings at boot via `registry.add_group(...)`; the registry dedupes and persists them.
 
 ## Usage
 
@@ -23,27 +23,30 @@ Declare permissions at module boot:
 
 ```python
 # modules/orders/orders/module.py
+from simple_module_core.permissions import PermissionRegistry
+
+
 class OrdersModule(ModuleBase):
     meta = ModuleMeta(name="orders")
 
-    def register_permissions(self):
-        return ["orders.read", "orders.write"]
+    def register_permissions(self, registry: PermissionRegistry) -> None:
+        registry.add_group("Orders", ["orders.read", "orders.write"])
 ```
 
 Guard a route:
 
 ```python
 from fastapi import APIRouter, Depends
-from permissions.deps import HasPermission   # type: ignore[import-not-found]
+from permissions.deps import RequiresPermission   # type: ignore[import-not-found]
 
 router = APIRouter()
 
 
-@router.get("/orders", dependencies=[Depends(HasPermission("orders.read"))])
+@router.get("/orders", dependencies=[Depends(RequiresPermission("orders.read"))])
 async def list_orders(): ...
 ```
 
-Admin flow: navigate to `/permissions/admin`, create a role, assign permissions, assign the role to users.
+Admin flow: navigate to `/users/admin`, create a role, assign permissions, assign the role to users.
 
 ## Depends on
 
diff --git a/modules/settings/README.md b/modules/settings/README.md
index cf145459..09a1e205 100644
--- a/modules/settings/README.md
+++ b/modules/settings/README.md
@@ -10,27 +10,32 @@ pip install simple_module_settings
 
 ## What it provides
 
-- `/settings` admin page aggregating every installed module's settings panel.
-- `register_settings_panel()` hook — a module declares `{title, inertia_page, requires_permission}`; `simple_module_settings` renders the tab.
-- DB-backed runtime settings table (separate from env-var-driven `SM_*` settings) for values admins change at runtime.
+- `/settings` admin page (and `/settings/modules`) aggregating every installed module's settings into one editable view.
+- `register_module_settings(app, package, SettingsClass, services_factory)` helper — a module calls this from its own `register_settings(app)` hook to record its `BaseSettings` class; the UI renders its fields automatically (no panel/page wiring needed).
+- DB-backed runtime settings store (hydrated into each module's `BaseSettings` at startup, before module `on_startup` hooks run) for values admins change at runtime.
 
 ## Usage
 
-Register a panel:
+Register a module's settings from its `register_settings(app)` hook:
 
 ```python
+from fastapi import FastAPI
+
+
 class OrdersModule(ModuleBase):
     meta = ModuleMeta(name="orders")
 
-    def register_settings_panel(self):
-        return {
-            "title": "Orders",
-            "inertia_page": "Orders/SettingsPanel",
-            "requires_permission": "orders.manage",
-        }
+    def register_settings(self, app: FastAPI) -> None:
+        from settings.registration import register_module_settings
+        from orders.settings import OrdersSettings
+        from orders.services import OrdersServices
+
+        register_module_settings(
+            app, "orders", OrdersSettings, lambda s: OrdersServices(settings=s)
+        )
 ```
 
-That adds an **Orders** tab at `/settings`. The rendered page is a regular Inertia page authored inside the `orders` module.
+That surfaces the module's settings fields under `/settings/modules`, hydrated from the DB store at startup. The settings class is a `pydantic_settings.BaseSettings` with the module's `SM_<PREFIX>_*` env-var defaults.
 
 ## Depends on
 
diff --git a/modules/users/README.md b/modules/users/README.md
index 8d761ca4..74ff9417 100644
--- a/modules/users/README.md
+++ b/modules/users/README.md
@@ -38,7 +38,7 @@ SM_USERS_BOOTSTRAP_PASSWORD=change-me
 Program:
 
 ```python
-from users.deps import CurrentUser    # type: ignore[import-not-found]
+from auth.deps import CurrentUser    # type: ignore[import-not-found]
 
 @router.get("/profile")
 async def profile(user: CurrentUser):
@@ -47,8 +47,8 @@ async def profile(user: CurrentUser):
 
 ## Depends on
 
-- `simple_module_core`, `simple_module_db`, `simple_module_hosting`, `simple_module_auth`
-- `fastapi-users[sqlalchemy]>=15,<16`, `aiosmtplib`, `cachetools`, `typer`
+- `simple_module_core`, `simple_module_db`, `simple_module_hosting`, `simple_module_settings`, `simple_module_auth`
+- `fastapi-users[sqlalchemy,oauth]>=15,<16`, `aiosmtplib`, `cachetools`, `typer`
 
 ## Social sign-in (Google, GitHub, Microsoft, OIDC)
 
diff --git a/packages/i18n/README.md b/packages/i18n/README.md
index 117d99dd..971f28d9 100644
--- a/packages/i18n/README.md
+++ b/packages/i18n/README.md
@@ -12,40 +12,34 @@ Peer-depends on React 19. Runtime deps `i18next` and `react-i18next` install aut
 
 ## What it provides
 
-- `createI18n({ locale, resources })` — returns a configured `i18next` instance.
-- `<I18nProvider>` — React context provider; plug it at the root of your Inertia app.
-- `useT(namespace?)` — hook returning the translation function, scoped if you pass a namespace.
-- `withNamespace(ns)` — higher-order helper for components that want a stable namespace binding.
+- `configureI18n({ locale, messages })` — initialise the shared `i18next` instance once at boot with the active-locale messages.
+- `updateI18n({ locale, messages })` — call when an Inertia visit brings a new locale (adds the resource bundle, switches language).
+- `useT()` — re-exported `react-i18next` `useTranslation` hook; returns `{ t }`.
+- `t` — non-hook translation accessor (re-exported from `i18next`) for use in schemas or utilities.
+- `keys` — generated, typed key tree (`keys.<module>.<...>`) you pass to `t()`.
 
 ## Usage
 
-Root setup (in `client_app/main.tsx`):
+Root setup (in `client_app`):
 
 ```tsx
-import { createI18n, I18nProvider } from "@simple-module-py/i18n";
-
-const i18n = createI18n({
-  locale: window.__INITIAL_LOCALE__ ?? "en",
-  resources: window.__I18N_RESOURCES__, // provided by InertiaLayoutDataMiddleware
-});
-
-function Root({ App, props }) {
-  return (
-    <I18nProvider i18n={i18n}>
-      <App {...props} />
-    </I18nProvider>
-  );
-}
+import { configureI18n, updateI18n } from "@simple-module-py/i18n";
+
+// On boot, from Inertia shared props (provided by InertiaLayoutDataMiddleware):
+configureI18n({ locale: props.i18n.locale, messages: props.i18n.messages ?? {} });
+
+// On every Inertia navigation that brings a new locale:
+updateI18n({ locale: nextLocale, messages: nextMessages });
 ```
 
 In a module page:
 
 ```tsx
-import { useT } from "@simple-module-py/i18n";
+import { keys, useT } from "@simple-module-py/i18n";
 
 export default function Browse() {
-  const t = useT("orders");
-  return <h1>{t("browse.title")}</h1>;  // resolves to orders.browse.title
+  const { t } = useT();
+  return <h1>{t(keys.orders.browse.title)}</h1>;  // resolves to orders.browse.title
 }
 ```
 
diff --git a/packages/tsconfig/README.md b/packages/tsconfig/README.md
index bd2ab1b2..0336f082 100644
--- a/packages/tsconfig/README.md
+++ b/packages/tsconfig/README.md
@@ -10,7 +10,7 @@ npm install --save-dev @simple-module-py/tsconfig
 
 ## What it provides
 
-- `base.json` — the canonical compiler options for simple_module apps. Targets ES2022, `strict: true`, `module: "ESNext"`, `moduleResolution: "bundler"`, JSX `react-jsx`, `allowImportingTsExtensions: true`, `verbatimModuleSyntax: true`.
+- `base.json` — the canonical compiler options for simple_module apps. Targets ES2022, `strict: true`, `module: "ESNext"`, `moduleResolution: "bundler"`, JSX `react-jsx`, `noEmit: true`, `esModuleInterop: true`, `skipLibCheck: true`, with `types: ["vite/client", "node"]`.
 
 ## Usage
 
diff --git a/packages/ui/README.md b/packages/ui/README.md
index a2af5ba3..1734225c 100644
--- a/packages/ui/README.md
+++ b/packages/ui/README.md
@@ -8,21 +8,21 @@ shadcn-derived React UI components and layouts for [simple_module](https://githu
 npm install @simple-module-py/ui
 ```
 
-Peer-depends on React 19. Assumes Tailwind CSS 4 is configured in the consuming app.
+Peer-depends on React 19, React DOM 19, and `@inertiajs/react` 2. Assumes Tailwind CSS 4 is configured in the consuming app.
 
 ## What it provides
 
-- Core primitives: `Button`, `Input`, `Label`, `Textarea`, `Select`, `Switch`, `Checkbox`.
-- Composite components: `Card`, `Dialog`, `Sheet`, `Popover`, `Tooltip`, `Toaster`, `Form` (react-hook-form bindings).
-- Layouts: `AppLayout` (sidebar + content), `AuthLayout` (centred form).
-- Small set of icons from `lucide-react`, re-exported.
+- shadcn primitives under `@simple-module-py/ui/components/ui/*`: `Button`, `Input`, `Label`, `Textarea`, `Select`, `Switch`, `Checkbox`, `Card`, `Dialog`, `Sheet`, `Popover`, `Tooltip`, `Form` (react-hook-form bindings), and many more.
+- Framework components under `@simple-module-py/ui/components/*` (also re-exported from the package root): `PageShell`, `SectionTitle`, `StatCard`, `FilterPills`, `NavIcon`, `ErrorBoundary`, `ErrorScreen`.
+- Layouts under `@simple-module-py/ui/layouts/*` (also re-exported from the root): `AppLayout`, `SidebarLayout`, `AuthenticatedLayout`, `AdminLayout`, `PublicLayout`, `AuthCardShell` (centred form).
 
 All components ship as `.ts` / `.tsx` source (no bundling step) — any modern bundler (Vite, Next, etc.) handles them transparently.
 
 ## Usage
 
 ```tsx
-import { Button, Card, CardHeader, CardContent, CardTitle } from "@simple-module-py/ui";
+import { Button } from "@simple-module-py/ui/components/ui/button";
+import { Card, CardHeader, CardContent, CardTitle } from "@simple-module-py/ui/components/ui/card";
 
 export default function ProductCard({ product }) {
   return (
@@ -51,8 +51,8 @@ At that point you've forked the library — `npm update` will no longer bring ch
 
 ## Depends on
 
-- `@simple-module-py/i18n`
-- Peer: `react ^19.0.0`
+- `@simple-module-py/i18n`, plus Radix/`radix-ui`, `lucide-react`, `recharts`, `sonner`, `class-variance-authority`, `clsx`, `tailwind-merge`, and other shadcn runtime deps.
+- Peer: `react ^19.0.0`, `react-dom ^19.0.0`, `@inertiajs/react ^2.0.0`
 
 ## License
 
diff --git a/skills/README.md b/skills/README.md
index 7d8be972..8c578988 100644
--- a/skills/README.md
+++ b/skills/README.md
@@ -47,7 +47,7 @@ The CLI is [vercel-labs/skills](https://github.com/vercel-labs/skills); see its
 | [simple-module-locales](./simple-module-locales/SKILL.md) | Adding or debugging i18n in a module — `locale_dirs()`, namespaces, CLDR plurals, the Zod-in-hook rule |
 | [simple-module-registries](./simple-module-registries/SKILL.md) | Contributing menu items, permissions, feature flags, or events from a module |
 | [simple-module-testing](./simple-module-testing/SKILL.md) | Writing pytest tests — picking the right fixture (`db_session` / `app` / `authenticated_client`), single-test runs, e2e |
-| [simple-module-doctor](./simple-module-doctor/SKILL.md) | Interpreting a diagnostic code (`SM001`–`SM018`) printed at boot |
+| [simple-module-doctor](./simple-module-doctor/SKILL.md) | Interpreting a diagnostic code (`SM001`–`SM021`) printed at boot |
 
 The skills are designed to stand alone — install them into any host or module-package project and they'll work without needing access to the framework's source repo.
 
diff --git a/skills/simple-module-cli/SKILL.md b/skills/simple-module-cli/SKILL.md
index e5be5343..0f2ac6e0 100644
--- a/skills/simple-module-cli/SKILL.md
+++ b/skills/simple-module-cli/SKILL.md
@@ -5,7 +5,7 @@ description: Use when invoking the `smpy` CLI for a simple_module_python project
 
 # simple_module_python: the `smpy` CLI
 
-The `smpy` command is provided by `simple_module_cli` (installed as a dep of `simple_module_hosting`). It groups four kinds of operations: scaffolding new things, project-time helpers for the host, admin shortcuts for the bundled modules, and installing the bundled agent skills.
+The `smpy` command is provided by `simple_module_cli` (installed as a dep of `simple_module_hosting`). It groups several kinds of operations: scaffolding new things, project-time helpers for the host, admin shortcuts for the bundled modules, installing the bundled agent skills, and bumping `simple_module_*` deps.
 
 ## Top-level commands
 
@@ -14,6 +14,7 @@ The `smpy` command is provided by `simple_module_cli` (installed as a dep of `si
 | `smpy new <name>` | Greenfield: scaffold a complete app (host + selected modules) in one shot, with an interactive wizard for DB / tenancy / module preset |
 | `smpy create-host <name>` | You want just a bare host project; you'll add modules later by `pip install`-ing them |
 | `smpy create-module <name>` | You're authoring a publishable module package (separate repo, distributed via PyPI) |
+| `smpy package-update` | Bump every `simple_module_*` / `simple-module-*` dependency in `pyproject.toml` to its latest non-yanked PyPI release (workspace/path/git/URL sources are left untouched) |
 | `smpy skills …` | Install / update the bundled agent-skill packs into a project (`add`, `list`, `update`) |
 | `smpy host …` | Project-time helpers run from inside a host directory (page manifest, JS dep sync) |
 | `smpy settings …` | Settings-module admin — currently `import-from-env` |
@@ -47,7 +48,7 @@ smpy new MyApp --no-install
 | `full` | every module in the catalog |
 | `custom` | interactive — pick each module yes/no |
 
-`--with` accepts a comma-separated list of catalog keys (`auth, users, permissions, products, dashboard, settings, feature_flags, file_storage, background_tasks, …`). Transitive `requires` are auto-added; the wizard prints `Added X (required by Y)` so you can see what got pulled in.
+`--with` accepts a comma-separated list of catalog keys (`auth, users, permissions, dashboard, settings, feature_flags, file_storage, background_tasks`). Transitive `requires` are auto-added; the wizard prints `Added X (required by Y)` so you can see what got pulled in.
 
 **Options summary:**
 
diff --git a/skills/simple-module-doctor/SKILL.md b/skills/simple-module-doctor/SKILL.md
index 96e38fb8..448cb774 100644
--- a/skills/simple-module-doctor/SKILL.md
+++ b/skills/simple-module-doctor/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: simple-module-doctor
-description: Use when interpreting a simple_module_python diagnostic code (SM001–SM018) printed at boot or by the diagnostics runner — what the code means, whether it's blocking, and the concrete fix. Triggers on any "SMnnn" code in logs, "InvalidModuleError", "module silently doesn't load", or "production failed boot".
+description: Use when interpreting a simple_module_python diagnostic code (SM001–SM021) printed at boot or by the diagnostics runner — what the code means, whether it's blocking, and the concrete fix. Triggers on any "SMnnn" code in logs, "InvalidModuleError", "module silently doesn't load", or "production failed boot".
 ---
 
 # simple_module_python: diagnostics
@@ -17,7 +17,7 @@ You can also call `run_diagnostics(...)` from `simple_module_core` programmatica
 | **SM003** | WARNING | A `pages/<Name>.tsx` exists but no `inertia.render("<Module>/<Name>", ...)` references it | Either delete the orphan file or wire up the render call |
 | **SM004** | WARNING | `inertia.render("<Module>/<Name>", ...)` is called but no matching `.tsx` exists | Fix the render-key typo or create the page file |
 | **SM007** | INFO | Module overrides no `register_*` hooks at all — likely scaffolded but empty | Either implement at least one hook or delete the module if unused |
-| **SM008** | ERROR | Two modules declare the same `ModuleMeta.name` (Postgres-schema / SQLite-prefix collision) | Rename one module's `meta.name` |
+| **SM008** | ERROR | Two modules declare the same `ModuleMeta.name` (their lowercased names would collide as table prefixes in the shared schema) | Rename one module's `meta.name` |
 | **SM009** | ERROR | A `framework/*` package directly imports from a plugin module (`modules/*`) | Move the symbol *up* into `simple_module_core` / `simple_module_hosting`, or invert the dependency via the event bus / a registry |
 | **SM010** | ERROR | Live DB revision is behind the migration head | Run `alembic upgrade head` before booting; in CI, ensure migrations are part of the deploy step |
 | **SM011** | WARNING | A module declares a SQLModel table that has no entry in migration history | Run `alembic revision --autogenerate -m "..."` and apply |
@@ -27,9 +27,12 @@ You can also call `run_diagnostics(...)` from `simple_module_core` programmatica
 | **SM015** | WARNING | A non-default locale has keys *not* present in the default | Remove dead keys from the non-default file or add them to default |
 | **SM016** | ERROR | A locale JSON file is invalid or contains non-string leaves | Fix the JSON; only string leaves are allowed (interpolation is `{name}` placeholders) |
 | **SM017** | WARNING | A module ships `.tsx` pages but is missing `package.json` / `tsconfig.json` | Add the JS workspace files so the host's frontend toolchain can resolve module imports |
-| **SM018** | WARNING | An Inertia page calls `router.{post,patch,put,delete}()` targeting `/api/*` | Use plain `fetch()` for JSON endpoints; Inertia's client expects an Inertia response, not JSON |
+| **SM018** | WARNING | An Inertia page calls `router.{post,patch,put,delete}()` targeting `/api/*` | Point the call at a view endpoint that returns `RedirectResponse(..., status_code=303)`, or use plain `fetch()` for the JSON endpoint; Inertia's client expects an Inertia response, not JSON |
+| **SM019** | WARNING | A module registers view routes (non-empty `view_prefix` + overrides `register_routes`) but overrides neither `register_menu_items` nor `register_permissions` — its pages exist with no sidebar entry and no role-editor visibility | Add `register_menu_items()` (sidebar) or `register_permissions()` (role editor), or clear `view_prefix` if the module is API-only |
+| **SM020** | ERROR | More than one auth provider module is installed | Install exactly one auth provider (e.g. `users` OR `keycloak`, not both) |
+| **SM021** | WARNING | No auth provider module is installed | Install an auth provider module (e.g. `simple-module-users` or `simple-module-keycloak`) |
 
-Codes `SM002`, `SM005`, `SM006` are reserved/retired — don't try to look them up. Output format is one line per finding, e.g. `[SM009] ERROR: <subject>`.
+Codes `SM002`, `SM005`, `SM006`, `SM012` are not part of this table — `SM002`/`SM005`/`SM006` are reserved/retired, and `SM012` (`register_settings` overridden but nothing on `app.state.<module_lower>`, WARNING, dev boot only) is raised from the hosting layer, not the core diagnostics runner. Output format is one line per finding, e.g. `[SM009] ERROR: <subject>`.
 
 Warnings are load-bearing: the framework only emits one when something concrete *will* break under a specific condition (locale switch, schema downgrade, deploy ordering). Ignored long enough they become the next on-call page. If you're suppressing warnings in CI to make it green, you're trading the CI signal for a production-boot failure later.
 
diff --git a/skills/simple-module-registries/SKILL.md b/skills/simple-module-registries/SKILL.md
index 37e3f122..c4014294 100644
--- a/skills/simple-module-registries/SKILL.md
+++ b/skills/simple-module-registries/SKILL.md
@@ -47,7 +47,7 @@ class OrdersModule(ModuleBase):
 
 The runtime expansion (role → permissions) is cached. `register_permissions` is called once at boot; mutating the registry afterwards bypasses the cache and invalidates user sessions until the cache TTL elapses. Don't mutate at request time.
 
-To check inside an endpoint, depend on the `RequireAnyPermissionDep` / `RequireAllPermissionsDep` dependencies (see auth/users), not by reading the registry by hand.
+To check inside an endpoint, depend on `RequiresPermission("<module>.<action>")` (from `simple_module_hosting.permissions`), not by reading the registry by hand. The dependency handles wildcard expansion and the 401-vs-403 distinction.
 
 ## Feature flags — `register_feature_flags(registry: FeatureFlagRegistry)`
 
@@ -132,7 +132,7 @@ Module A consuming Module B's events should import only from `b.contracts.events
 ## Pitfalls
 
 - **Mutated a registry after boot.** Boot-phase only. Cached views (menus, role→permission map) aren't invalidated for live requests; mutations look fine in dev with auto-reload and silently rot in prod.
-- **Raw permission strings in endpoints (`request.state.user.permissions`).** Use `RequireAnyPermissionDep` / `RequireAllPermissionsDep`. The dependency handles wildcard expansion and 401 vs 403 distinction.
+- **Raw permission strings in endpoints (`request.state.user.permissions`).** Use `RequiresPermission(...)`. The dependency handles wildcard expansion and the 401-vs-403 distinction.
 - **Forgot a feature flag's `default_enabled=False`.** A flag added with `default_enabled=True` is on for every tenant on first deploy — defeats the point of gating a rollout. Default to `False`; flip via override after the rollout window.
 - **Subscribed to an event in `register_settings` instead of `register_event_handlers`.** `register_settings` runs **before** the event bus is constructed; the subscription silently no-ops.
 - **Used `publish_nowait` inside a request handler that needs the listener to commit a DB row in the same transaction.** It returns immediately — the handler runs after the request has already committed/rolled back. For "in this request, do X then Y", just call Y directly.