@hartl-services/medusa-base 3.0.0 → 5.0.0

package/README.md

@@ -1,75 +1,128 @@
 # Medusa Base
 
-Medusa v2.19 base plugin for Hartl Services shops. Every shop installs it. It
-provides per-plugin feature toggles, runtime settings and actions: a generic
-Admin hub under **Settings → Hartl Services Plugins** with one page per
-plugin, a Store endpoint for storefronts and helpers that plugins use to
-enforce their toggles and read their settings. Since 1.0.0 it also contains
-the shop's transactional E-Mail, order Documents (invoices, cancellations,
-packing lists) and S3 file storage, and the turnkey `medusa-config.ts` preset,
-and since 3.0.0 the EU tax compliance (UID check, Tax provider) (see "E-Mail",
-"Dokumente", "Steuer-Compliance", "Dateispeicher (S3)" and
-"Shop-Config-Preset").
-
-## What it does
-
-- Discovers every registered module whose service declares `pluginFeatures`
-  (see below). No plugin has to register itself anywhere else.
-- Stores one row per plugin in `plugin_feature_state` (module
-  `plugin_features`): the plugin switch, the configured feature values and a
-  `version` for optimistic concurrency.
-- Serves the effective values to storefronts and the configured plus effective
-  values to the Admin.
-- Exports `definePluginFeatures`, `requirePluginFeature` and
-  `isPluginFeatureEnabled` from `@hartl-services/medusa-base` for plugins.
-- Emits `plugin-features.updated.v1` after every saved Admin toggle update
-  (see "Toggle-change event").
-- Stores runtime settings that plugins declare (secrets encrypted), resolves
-  them with the medusa-config fallback and exports `getPluginSettings` (see
-  "Runtime settings").
-- Runs actions that plugins declare as workflow ids, records every run with
-  its progress and outcome and rejects a second start while one runs (see
-  "Actions").
-- Holds the shop's master data (Firmenangaben) as its own settings and
-  exports `getShopMasterData` (see "Shop-Stammdaten").
-- Exports Admin components from `@hartl-services/medusa-base/admin-components`
-  (also `sdk`, `getErrorMessage` and the rich-text editor) and server helpers
-  from `@hartl-services/medusa-base/lib` (`toWireResponse`) so a plugin composes the base's sections into its own page and hides
-  widgets of disabled features (see "Admin components for plugin pages").
-- Owns the `completeCartWorkflow` hooks `validate` and `orderCreated` and runs
-  the workflows that plugins declare for them (see "Complete-cart hook
-  composition").
-- Redirects `GET /` to the admin dashboard and repairs dangling
-  `cart_promotion` links (see "Root redirect" and "Cart-promotion link
-  repair").
-- Requires passwords of at least 15 characters for Admin users and, by
-  default, customers; shops can set their own customer rules (see "Password
-  policy").
-- Starts Admin draft orders without a customer order confirmation and marks
-  placed 0 € orders without payment as paid (see "Draft orders and 0 €
-  orders").
-- Exports the shop's `medusa-config.ts` helpers from
+Medusa v2.19 base plugin for Hartl Services shops. Every shop installs it,
+first in its plugin list, because the other Hartl Services plugins read their
+feature toggles through it: it provides per-plugin feature toggles, runtime
+settings and actions, a generic Admin hub under **Settings → Hartl Services
+Plugins** with one page per plugin, a Store endpoint for storefronts and
+helpers that plugins use to enforce their toggles and read their settings.
+Since 1.0.0 it also contains the shop's transactional E-Mail, order Documents
+(invoices, cancellations, packing lists), S3 file storage and the turnkey
+`medusa-config.ts` preset, since 3.0.0 the EU tax compliance (UID check, Tax
+provider) and since 5.0.0 the free-shipping thresholds. The "Overview" lists
+every area with its section; "Upgrading" collects the version notes.
+
+## Table of contents
+
+- [Overview](#overview)
+- [Installation in a shop](#installation-in-a-shop)
+- [Upgrading](#upgrading)
+  - [Upgrading to 0.4.0](#upgrading-to-040)
+  - [Upgrading to 0.4.1](#upgrading-to-041)
+  - [Upgrading to 1.0.0](#upgrading-to-100)
+  - [Upgrading to 3.0.0](#upgrading-to-300)
+  - [Upgrading to 4.0.0](#upgrading-to-400)
+  - [Upgrading to 5.0.0](#upgrading-to-500)
+- [Shop-Config-Preset](#shop-config-preset)
+  - [Installing the preset](#installing-the-preset)
+  - [Usage](#usage)
+  - [API](#api)
+  - [Options](#options)
+  - [Environment variables](#environment-variables)
+  - [Fixed configuration](#fixed-configuration)
+- [Plugin platform](#plugin-platform)
+  - [HTTP endpoints](#http-endpoints)
+  - [Declaring features in a plugin](#declaring-features-in-a-plugin)
+  - [Runtime settings](#runtime-settings)
+  - [Actions](#actions)
+  - [Shop-Stammdaten](#shop-stammdaten)
+  - [Admin pages](#admin-pages)
+  - [Semantics](#semantics)
+  - [Complete-cart hook composition](#complete-cart-hook-composition)
+- [Built-in features](#built-in-features)
+  - [Kunden-Login](#kunden-login)
+  - [E-Mail](#e-mail)
+  - [Dokumente](#dokumente)
+  - [Steuer-Compliance](#steuer-compliance)
+  - [Versandkostenfrei](#versandkostenfrei)
+  - [Dateispeicher (S3)](#dateispeicher-s3)
+- [Shop behaviour and operations](#shop-behaviour-and-operations)
+  - [Root redirect](#root-redirect)
+  - [Cart-promotion link repair](#cart-promotion-link-repair)
+  - [Draft orders and 0 € orders](#draft-orders-and-0--orders)
+  - [Password policy](#password-policy)
+  - [Config helpers](#config-helpers)
+  - [Sentry logger wrapper](#sentry-logger-wrapper)
+  - [Sentry instrumentation](#sentry-instrumentation)
+- [Development](#development)
+  - [Local e-mail development](#local-e-mail-development)
+  - [Build output of `/admin-components`](#build-output-of-admin-components)
+
+## Overview
+
+- **Feature toggles** (see "Plugin platform"): discovers every registered
+  module whose service declares `pluginFeatures`, so no plugin has to register
+  itself anywhere else; stores one row per plugin in `plugin_feature_state`
+  (module `plugin_features`) with the plugin switch, the configured feature
+  values and a `version` for optimistic concurrency; serves the effective
+  values to storefronts and the configured plus effective values to the Admin
+  (see "HTTP endpoints"); exports `definePluginFeatures`,
+  `requirePluginFeature` and `isPluginFeatureEnabled` from
+  `@hartl-services/medusa-base` for plugins (see "Declaring features in a
+  plugin") and emits `plugin-features.updated.v1` after every saved Admin
+  toggle update (see "Toggle-change event").
+- **Runtime settings**: stores runtime settings that plugins declare (secrets
+  encrypted), resolves them with the medusa-config fallback and exports
+  `getPluginSettings` (see "Runtime settings").
+- **Actions**: runs actions that plugins declare as workflow ids, records every
+  run with its progress and outcome and rejects a second start while one runs
+  (see "Actions").
+- **Shop-Stammdaten**: holds the shop's master data (Firmenangaben) as its own
+  settings and exports `getShopMasterData` (see "Shop-Stammdaten").
+- **Admin components and server helpers**: exports Admin components from
+  `@hartl-services/medusa-base/admin-components` (also `sdk`,
+  `getErrorMessage` and the rich-text editor) and server helpers from
+  `@hartl-services/medusa-base/lib` (`toWireResponse`) so a plugin composes
+  the base's sections into its own page and hides widgets of disabled
+  features (see "Admin pages" and "Admin components for plugin pages").
+- **Complete-cart hooks**: owns the `completeCartWorkflow` hooks `validate`
+  and `orderCreated` and runs the workflows that plugins declare for them (see
+  "Complete-cart hook composition").
+- **Kunden-Login**: declares which login methods customers may use (module
+  `customer_auth`: e-mail + password and a one-time code by e-mail), provides
+  the `email-otp` auth provider and the code request route (see
+  "Kunden-Login"); requires passwords of at least 15 characters for Admin
+  users and, by default, customers, and lets shops set their own customer
+  rules (see "Password policy").
+- **E-Mail**: sends the shop's transactional e-mails over SMTP or Microsoft
+  365, chosen in the Admin (module `email`, see "E-Mail").
+- **Dokumente**: issues invoices, cancellation documents and packing lists as
+  private PDFs (module `documents`, see "Dokumente").
+- **Steuer-Compliance**: checks B2B customers' VAT IDs (FinanzOnline),
+  provides the Medusa Tax provider `tp_tax_compliance` for reverse-charge and
+  apportioned shipping tax and freezes the tax evidence of an order at
+  checkout (module `tax_compliance`, see "Steuer-Compliance").
+- **Versandkostenfrei**: keeps the two automatic free-shipping promotions
+  (shop-wide and affiliate threshold) in sync with their Admin settings
+  (module `free_shipping`, see "Versandkostenfrei").
+- **Dateispeicher (S3)**: stores files in S3-compatible storage behind the
+  `/files` gateway (see "Dateispeicher (S3)").
+- **Shop behaviour**: redirects `GET /` to the admin dashboard, repairs
+  dangling `cart_promotion` links, starts Admin draft orders without a
+  customer order confirmation and marks placed 0 € orders without payment as
+  paid (see "Root redirect", "Cart-promotion link repair" and "Draft orders
+  and 0 € orders").
+- **Shop configuration**: builds a shop's complete `medusa-config.ts` from a
+  few shop facts (`@hartl-services/medusa-base/shop-config`, see
+  "Shop-Config-Preset"); exports the generic `medusa-config.ts` helpers from
   `@hartl-services/medusa-base/config` and Sentry's `register()` from
-  `@hartl-services/medusa-base/instrumentation` (see "Config helpers" and
-  "Sentry instrumentation").
-- Sends the shop's transactional e-mails over SMTP or Microsoft 365, chosen in the Admin (module `email`, see
-  "E-Mail"), issues invoices, cancellation documents and packing lists as
-  private PDFs (module `documents`, see "Dokumente") and stores files in
-  S3-compatible storage behind the `/files` gateway (see "Dateispeicher (S3)").
-- Checks B2B customers' VAT IDs (FinanzOnline), provides the Medusa Tax
-  provider `tp_tax_compliance` for reverse-charge and apportioned shipping tax
-  and freezes the tax evidence of an order at checkout (module
-  `tax_compliance`, see "Steuer-Compliance").
-- Declares which login methods customers may use (module `customer_auth`:
-  e-mail + password and a one-time code by e-mail), provides the `email-otp`
-  auth provider and the code request route (see "Kunden-Login").
-- Builds a food shop's complete `medusa-config.ts` from a few shop facts
-  (`@hartl-services/medusa-base/shop-config`, see "Shop-Config-Preset").
+  `@hartl-services/medusa-base/instrumentation` (see "Config helpers",
+  "Sentry logger wrapper" and "Sentry instrumentation").
 
 ## Installation in a shop
 
 ```bash
-pnpm add @hartl-services/medusa-base @hartl-services/medusa-food-supplements-contracts
+pnpm add @hartl-services/medusa-base @hartl-services/medusa-contracts
 ```
 
 ```ts
@@ -105,11 +158,35 @@ every module of the plugin; each module reads only its own namespace:
 `options: {}` is valid: the base then only provides the feature toggles,
 settings, actions and hooks, the e-mail module cannot dispatch, documents use
 the defaults and the `/files` routes answer that signing is not configured.
-Run `medusa db:migrate` after installing it (and after upgrading: 0.4.0 adds
-the tables `plugin_setting_state` and `plugin_action_run`; 1.0.0 brings the
-`email` and `documents` tables of the former `@hartl-services/medusa-email` and
-`@hartl-services/medusa-documents` packages with unchanged table and
-migration names, so a shop that used them needs no data migration).
+Run `medusa db:migrate` after installing it and after every upgrade (see
+"Upgrading").
+
+Peer dependencies are the host's Medusa 2.19 packages (`@medusajs/framework`,
+`@medusajs/medusa`, `@medusajs/admin-sdk`, `@medusajs/js-sdk`, `@medusajs/ui`, `@medusajs/icons`)
+plus React, React Router and TanStack Query in the versions the Medusa 2.19
+dashboard uses.
+
+## Upgrading
+
+Run `medusa db:migrate` after every upgrade. The versions below add tables or
+migration scripts, merge former packages into the base or rename exports.
+
+### Upgrading to 0.4.0
+
+0.4.0 adds the tables `plugin_setting_state` and `plugin_action_run`.
+
+### Upgrading to 0.4.1
+
+`medusa db:migrate` runs the migration script
+`dismiss-orphaned-cart-promotion-links` once (see "Cart-promotion link
+repair"); nothing to configure.
+
+### Upgrading to 1.0.0
+
+1.0.0 brings the `email` and `documents` tables of the former
+`@hartl-services/medusa-email` and `@hartl-services/medusa-documents` packages
+with unchanged table and migration names, so a shop that used them needs no
+data migration.
 
 Upgrading from the separate packages: remove `@hartl-services/medusa-email`,
 `@hartl-services/medusa-documents`, `@hartl-services/medusa-s3-cache-storage`
@@ -122,7 +199,9 @@ exports from the matching `@hartl-services/medusa-base` subpath. The
 `documentsEnabled` option is gone; Documents is always installed, and the
 e-mail module follows the Documents `invoices` toggle.
 
-Upgrading to 3.0.0 (Steuer-Compliance merged): remove
+### Upgrading to 3.0.0
+
+Steuer-Compliance was merged into the base: remove
 `@hartl-services/medusa-tax-compliance` from `package.json` and from the
 `plugins` list and change the Tax provider resolve path to
 `@hartl-services/medusa-base/providers/tax-compliance` (the provider id
@@ -133,12 +212,158 @@ reached `tax_compliance` by container key keep working; the typed helper is
 Hartl Services plugins need the versions released with 3.0.0 (their peer
 range is `^3`).
 
-Peer dependencies are the host's Medusa 2.19 packages (`@medusajs/framework`,
-`@medusajs/medusa`, `@medusajs/admin-sdk`, `@medusajs/js-sdk`, `@medusajs/ui`, `@medusajs/icons`)
-plus React, React Router and TanStack Query in the versions the Medusa 2.19
-dashboard uses.
+### Upgrading to 4.0.0
+
+Renames: the Contracts package is
+`@hartl-services/medusa-contracts` (1.0.0, formerly
+`@hartl-services/medusa-food-supplements-contracts`; same subpaths), and the
+Shop-Config-Preset exports are `buildShopConfig`, `defineShopConfig`,
+`ShopConfigOptions`, `ShopConfigInput`, `ShopPlugin` and `ShopModule`
+(formerly `buildFoodShopConfig` etc.). Replace the import names in
+`medusa-config.ts` and the Contracts package name in the shop and its
+Storefront; nothing else changes. The other Hartl Services plugins need the
+versions released with 4.0.0 (peer range `^4`).
+
+### Upgrading to 5.0.0
+
+Versandkostenfrei was merged into the base: remove
+`@hartl-services/medusa-free-shipping` from `package.json` and from the
+`plugins` list (the module key `free_shipping`, its migrations, settings,
+promotions, job and subscriber ids are unchanged, so no data migration is
+needed; a shop that keeps the old package registered fails at boot with a
+duplicate `free_shipping` module). The other Hartl Services plugins need the
+versions released with 5.0.0 (peer range `^5`).
+
+## Shop-Config-Preset
+
+`@hartl-services/medusa-base/shop-config` turns a shop's configuration
+from about 290 lines into about 30: the plugin list and order, the Redis event
+bus, SMTP notifications, S3 file storage, the tax and Stripe payment providers,
+the Admin path, the Sentry logger bridge and the environment validation are
+assembled there; the shop supplies only its own facts. It reuses the `/config`
+helpers (see "Config helpers") for environment parsing. It is a separate subpath because it
+loads the Sentry logger wrapper and with it `@sentry/node`; `/config` stays
+free of it.
+
+The preset registers the base (with its E-Mail, Documents and `/files`
+options, and its Tax provider) plus three feature plugins, in this order:
+`medusa-base`, `medusa-batch-management`,
+`medusa-affiliate`, `medusa-payload-sync`.
+
+### Installing the preset
+
+```bash
+pnpm add @hartl-services/medusa-base \
+  @hartl-services/medusa-batch-management \
+  @hartl-services/medusa-affiliate \
+  @hartl-services/medusa-payload-sync \
+  @medusajs/event-bus-redis @medusajs/payment-stripe \
+  @sentry/node
+```
+
+### Usage
+
+```ts
+// medusa-config.ts
+import { defineShopConfig } from "@hartl-services/medusa-base/shop-config"
+
+module.exports = defineShopConfig({
+  displayName: "EXAMPLE SHOP",
+  orderNotificationEmail: "orders@example.com",
+  timeZone: "Europe/Vienna",
+  storefrontCountryCode: "de",
+})
+```
+
+A shop that has to adjust the result (a test harness, for example) builds the
+plain input, changes it and calls `defineConfig` itself:
+
+```ts
+import { defineConfig } from "@medusajs/framework/utils"
+import { buildShopConfig } from "@hartl-services/medusa-base/shop-config"
+
+const config = buildShopConfig(options)
+config.plugins = config.plugins.filter(
+  (plugin) => plugin.resolve !== "@hartl-services/medusa-batch-management",
+)
+module.exports = defineConfig(config)
+```
+
+### API
+
+- `defineShopConfig(options, environment = process.env)` returns
+  `defineConfig(buildShopConfig(options, environment))`.
+- `buildShopConfig(options, environment = process.env)` returns the plain
+  config input (`admin`, `logger`, `projectConfig`, `modules`, `plugins`)
+  before `defineConfig`. `modules` and `plugins` are ordinary arrays.
+- Types: `ShopConfigOptions`, `ShopConfigInput`, `ShopPlugin`,
+  `ShopModule`.
+
+Both functions validate the options first and throw a `TypeError` naming the
+option (`Shop option "timeZone" must be ...`), so a misconfigured shop
+fails at boot. They then load the `.env` file (unless disabled) and read and
+validate the environment; a missing variable fails with the variable's name.
+
+### Options
+
+| Option | Meaning |
+| --- | --- |
+| `displayName` | Shop name in the default e-mail templates (a shop's initial seed may use it as store name). Company name, address and UID are no options: documents and tax compliance read them only from the Shop-Stammdaten (Admin, "Hartl Services Plugins"). |
+| `orderNotificationEmail` | Receives order notification e-mails; must look like an e-mail address. |
+| `timeZone` | IANA time zone (validated with `Intl`). Chooses the annual document-number period, the printed dates on documents and the affiliate consignment reminder time zone. |
+| `storefrontCountryCode` | 2-letter lowercase country code of the storefront route. Links: `<STOREFRONT_URL>/<cc>/partnerportal` (affiliate portal), `<STOREFRONT_URL>/<cc>/reset-password` and `<STOREFRONT_URL>/<cc>/verify-account` (the e-mail plugin appends `#token=`), referral base `<STOREFRONT_URL>/<cc>`. The Admin invite link is `<MEDUSA_BACKEND_URL>/app/invite?token=`. |
+| `documentHtmlFactory` | Optional `DocumentHtmlFactory` that replaces the default document markup, typically `createDefaultDocumentHtmlFactory({ timeZone, theme })` from `/config` with the shop's CSS and watermark (see "Layout, logo, payment terms and shop theme"). Must be a function. |
+| `loadEnvFile` | Default `true`: calls `loadEnv(NODE_ENV \|\| "development", process.cwd())`. Pass `false` when the environment is already complete (tests, isolated child processes). |
+
+### Environment variables
+
+Required at runtime (during `medusa build`, with `MEDUSA_BUILD_PHASE=true`, the
+plugins' build placeholders stand in for them):
+
+- Medusa core: `DATABASE_URL`, `STORE_CORS`, `ADMIN_CORS`, `AUTH_CORS`,
+  `JWT_SECRET`, `COOKIE_SECRET`, `MEDUSA_BACKEND_URL`, `STOREFRONT_URL` (plain
+  HTTP origins are accepted only in development and test).
+- Redis: `REDIS_URL` (optional in development, where Medusa's local event bus
+  is used; required elsewhere, `rediss://` with authentication in production
+  unless `REDIS_ALLOW_INSECURE_PRIVATE_NETWORK=true`). Never used during a
+  build.
+- SMTP: `SMTP_HOST`, `SMTP_PORT`, `SMTP_SECURE`, `SMTP_USER`, `SMTP_PASSWORD`,
+  `SMTP_FROM`, `SMTP_REQUIRE_TLS` (outside development and test either
+  `SMTP_SECURE` or `SMTP_REQUIRE_TLS` must be `true`).
+- Stripe: `STRIPE_API_KEY` (`sk_...`), `STRIPE_WEBHOOK_SECRET` (`whsec_...`).
+- S3: `S3_CACHE_STORAGE_BUCKET`, `S3_CACHE_STORAGE_REGION`.
+- Documents: `DOCUMENT_PDF_EXECUTABLE`.
+
+Optional: `S3_CACHE_STORAGE_ENDPOINT`, `S3_CACHE_STORAGE_FORCE_PATH_STYLE`,
+`S3_CACHE_STORAGE_PREFIX`, `S3_CACHE_STORAGE_ACCESS_KEY_ID`,
+`S3_CACHE_STORAGE_SECRET_ACCESS_KEY`, `S3_CACHE_STORAGE_SESSION_TOKEN` (omit
+the keys to use the AWS credential chain), `S3_CACHE_STORAGE_CACHE_DIR`
+(default `./.medusa-s3-cache`), `S3_CACHE_STORAGE_TTL_MS`,
+`S3_CACHE_STORAGE_CLEANUP_INTERVAL_MS`,
+`S3_CACHE_STORAGE_EXPIRATION_STRATEGY`,
+`FILE_GATEWAY_PRIVATE_DOWNLOAD_DURATION_SECONDS`, and `SENTRY_DSN` /
+`SENTRY_ENVIRONMENT` for error tracking (see the base's
+`/instrumentation`).
+
+### Fixed configuration
+
+Not configurable on purpose: the plugin order (base first), the Redis event
+bus job policy (3 attempts, exponential backoff from 1 s), S3 cache defaults
+(15 min cleanup, 1 h TTL, absolute expiration), Stripe immediate capture with
+automatic payment methods, the 24 h session lifetime, Admin path `/app`,
+consignment reminders due on day 10, the Documents module always being part of the base, and
+`http.authVerificationsPerActor.customer` (a getter that follows the E-Mail `customer_verification` toggle, see
+"Kontobestätigung per E-Mail"), `http.authMethodsPerActor` (customers: a getter that follows the `customer_auth` switches; Admin users: `["emailpass"]`) and the auth module entry
+(providers `emailpass` and `email-otp`, the latter with `hmacSecret` = `JWT_SECRET`, the same value as `http.jwtSecret`; see
+"Kunden-Login").
+
+## Plugin platform
 
-## HTTP endpoints
+The mechanics every plugin builds on: the HTTP surface, the feature
+declaration, runtime settings, actions, the shop master data, the Admin and
+server helpers, the toggle semantics and the complete-cart hooks.
+
+### HTTP endpoints
 
 | Method | Path | Auth | Response |
 |---|---|---|---|
@@ -174,8 +399,8 @@ Store values are effective values only; a storefront uses them to hide
 features. DTOs, schemas and paths come from the Contracts package:
 
 ```ts
-import type { StorePluginFeaturesListResponse } from "@hartl-services/medusa-food-supplements-contracts/types/plugin-features-store"
-import { pluginFeaturesStorePaths } from "@hartl-services/medusa-food-supplements-contracts/paths/plugin-features"
+import type { StorePluginFeaturesListResponse } from "@hartl-services/medusa-contracts/types/plugin-features-store"
+import { pluginFeaturesStorePaths } from "@hartl-services/medusa-contracts/paths/plugin-features"
 
 const { plugins } = await sdk.client.fetch<StorePluginFeaturesListResponse>(
   pluginFeaturesStorePaths.get.list,
@@ -183,7 +408,7 @@ const { plugins } = await sdk.client.fetch<StorePluginFeaturesListResponse>(
 )
 ```
 
-## Declaring features in a plugin
+### Declaring features in a plugin
 
 A plugin depends on `@hartl-services/medusa-base` (peer dependency), declares
 its features once and exposes the declaration as `pluginFeatures` on its
@@ -223,7 +448,7 @@ base's own shop master data): the Admin shows no plugin switch, `enabled` is
 always `true` whatever is stored, and `POST /admin/plugin-features` with
 `enabled: false` is 400. It cannot be combined with `default_enabled: false`.
 
-### Presentation fields for the Admin page
+#### Presentation fields for the Admin page
 
 All optional; the Admin response always carries them (`null`, `[]` or
 `"full"` when not declared). Texts are non-empty trimmed strings;
@@ -266,7 +491,7 @@ All optional; the Admin response always carries them (`null`, `[]` or
   share a two-column row; not for `boolean`) and `section` (sub-heading inside
   the group, shared by consecutive settings with the same value).
 
-### Gating routes
+#### Gating routes
 
 Put gate entries at the start of the plugin's `routes` array. An entry without
 `methods` is a prefix match and runs before every method-specific middleware:
@@ -293,7 +518,7 @@ export default defineMiddlewares({
 A disabled plugin or feature answers 404. With several keys, all must be
 enabled. The toggles are read once per request.
 
-### Gating subscribers and jobs
+#### Gating subscribers and jobs
 
 Return early:
 
@@ -314,7 +539,7 @@ To check another plugin without importing it, use its plugin key:
 the descriptor among the registered modules; an unknown or uninstalled plugin
 key (and an undeclared feature key) is `false`.
 
-### Toggle-change event
+#### Toggle-change event
 
 After a successful `POST /admin/plugin-features` the base emits
 `PLUGIN_FEATURES_UPDATED_EVENT` (`plugin-features.updated.v1`) through the
@@ -332,7 +557,7 @@ subscribes to it and filters on its own `plugin_key`:
 import {
   PLUGIN_FEATURES_UPDATED_EVENT,
   PluginFeaturesUpdatedEventSchema,
-} from "@hartl-services/medusa-food-supplements-contracts/events/plugin-features"
+} from "@hartl-services/medusa-contracts/events/plugin-features"
 
 export default async function onToggleChange({ event, container }: SubscriberArgs<unknown>) {
   const payload = PluginFeaturesUpdatedEventSchema.parse(event.data)
@@ -346,7 +571,7 @@ export const config: SubscriberConfig = { event: PLUGIN_FEATURES_UPDATED_EVENT }
 Events can arrive late or twice; re-read the current toggles instead of
 trusting the payload for anything that writes.
 
-### Never on the cart path
+#### Never on the cart path
 
 Code on the cart and checkout hot path (cart middlewares, cart workflow hooks,
 `orderCreated` handling, cart subscribers) must never read toggles. It stays
@@ -356,7 +581,7 @@ existing data. Login is not the cart path: the E-Mail plugin's
 `customer_verification` toggle does switch customer logins, through an
 in-memory copy of the toggle (see "Kontobestätigung per E-Mail").
 
-## Runtime settings
+### Runtime settings
 
 Configuration a plugin reads at RUN time (for example an external system's
 URL and API key) is declared in the descriptor and edited on the plugin's
@@ -450,7 +675,7 @@ class DemoModuleService extends MedusaService({ /* models */ }) {
   (`plugin-settings.updated.v1`) with `{ plugin_key, version, changed_keys }`
   (no values). Direct service calls emit nothing.
 
-### Secrets
+#### Secrets
 
 Secrets are stored AES-256-GCM encrypted (`{ enc: "<base64 iv|tag|ciphertext>" }`
 in `plugin_setting_state.values`) with a key derived by HKDF-SHA256 from the
@@ -465,7 +690,7 @@ applies in the meantime. Secrets saved by an unpublished development build
 before the key binding existed count as "nicht gesetzt" the same way and must
 be entered again.
 
-## Actions
+### Actions
 
 A plugin declares actions as registered workflow ids; the base runs them from
 the plugin's Admin page:
@@ -519,7 +744,7 @@ Admin user id, `run_id` the recorded run).
   workflow is not registered is 500 (`UNEXPECTED_STATE` naming the workflow,
   no run is recorded).
 
-### Reporting progress
+#### Reporting progress
 
 A long-running action reports progress from its workflow; the Admin shows it
 as a bar ("current / total") with the label:
@@ -548,7 +773,7 @@ characters. Without a `run_id` (the same workflow run from a script) the
 helper does nothing; invalid progress, an unknown or finished run and a
 failed write are logged as a warning and dropped, and never fail the action.
 
-## Shop-Stammdaten
+### Shop-Stammdaten
 
 The base declares its own descriptor on its module service
 (`plugin_key: "shop"`, label "Shop-Stammdaten", `switchable: false`, no
@@ -616,7 +841,7 @@ Documents plugin into the appearance: the Documents logo, else the E-Mail
 logo; a `logo` stored in the Shop-Stammdaten by an earlier release is kept
 only when neither plugin had one.
 
-## Admin pages
+### Admin pages
 
 - `/settings/hartl-services` (sidebar entry "Hartl Services Plugins") is the
   hub: a banner for the Shop-Stammdaten (icon, summary, "Nicht konfiguriert"
@@ -645,7 +870,7 @@ only when neither plugin had one.
   rejects a path outside `/settings/hartl-services/` or under
   `/settings/hartl-services/plugin/`.
 
-### Admin components for plugin pages
+#### Admin components for plugin pages
 
 `@hartl-services/medusa-base/admin-components` (ESM for the Admin's vite
 build, with types) exports:
@@ -744,7 +969,7 @@ The consuming plugin lists `@hartl-services/medusa-base` in its
 external and the shop's Admin resolves one shared copy. The components use
 the host Admin's React, React Query, React Router and `@medusajs/ui`.
 
-#### Rich-text editor
+##### Rich-text editor
 
 `useRichTextEditor(config, initialContent, deps)` returns the TipTap
 `Editor | null` (`null` until it exists), `<RichTextEditor editor
@@ -837,7 +1062,7 @@ policy (`link.isAllowedHref`) are read on every use and always see the latest
 render, so they need no stable reference. Pass `[]` for an editor that lives as
 long as its component.
 
-### Server helpers
+#### Server helpers
 
 `@hartl-services/medusa-base/lib` (server and isomorphic code; a separate
 subpath because unit tests mock `@hartl-services/medusa-base` wholesale)
@@ -883,13 +1108,7 @@ The main entry (`@hartl-services/medusa-base`) additionally exports, next to
 | `isOwnPluginEvent(data, pluginKey)` | `true` when the event payload's `plugin_key` is `pluginKey`; never throws. For subscribers of `plugin-features.updated.v1` and `plugin-settings.updated.v1` |
 | `isBasePluginRegistered(container)` / `resolveBaseModule(container)` | Whether the base module is registered (boot-time check) / its service, or `UNEXPECTED_STATE` |
 
-`/admin-components` is built (after `medusa plugin:build`) into
-`.medusa/server/src/admin/admin-components`, not into `dist`: the host Admin's
-Tailwind scans only `.medusa/server/src/admin/**` of a plugin, so the classes of
-the shared components are generated there. Do not move the outDir of
-`tsconfig.admin-components.json`.
-
-## Semantics
+### Semantics
 
 - No stored row: every value is its declared default, `version` is 0.
 - `effective(feature) = plugin enabled && configured(feature) && effective(parent)`.
@@ -901,7 +1120,7 @@ the shared components are generated there. Do not move the outDir of
   value updates exactly that version. A concurrent change answers 409; the
   Admin page reloads and shows a notice.
 
-## Complete-cart hook composition
+### Complete-cart hook composition
 
 **Why.** Medusa 2.19.0 allows exactly one handler per workflow hook; a second
 registration throws "Cannot define multiple hook handlers" at boot. Several
@@ -986,42 +1205,12 @@ Storefront calls it right before confirming a payment. Plugins that guard
 `/store/carts/:id/complete` with a middleware register it for this route too
 (the affiliate plugin's registered-email gate does).
 
+## Built-in features
 
-## Sentry logger wrapper
-
-`@hartl-services/medusa-base/sentry-logger` exports `withSentryErrorReporting(logger)`,
-formerly published as `@hartl-services/medusa-sentry-logger`. Medusa's HTTP
-error handler catches thrown route and workflow errors and only logs them, so
-Sentry's default Node integrations never see them; wrapping the logger reports
-every `logger.error(...)` and every `Error` passed to `logger.warn(...)` (at
-level `warning`). It is a plain library import for `medusa-config.ts`, not a
-Medusa plugin feature, and needs `@sentry/node` (an optional peer dependency):
-
-```ts
-import { logger } from "@medusajs/framework/logger";
-import { withSentryErrorReporting } from "@hartl-services/medusa-base/sentry-logger";
-
-module.exports = defineConfig({
-  logger: withSentryErrorReporting(logger),
-  // ...
-});
-```
-
-Initialize Sentry in `instrumentation.ts` as usual; without a `SENTRY_DSN` the
-wrapper is inert.
-
-## Root redirect
-
-Medusa serves nothing at `/`, so a deployed domain answers it with a 404. The
-base registers `GET /` and answers with a `302` to the shop's `admin.path`
-(read from the config module, fallback `/app`), so opening the bare domain
-lands on the admin dashboard in every shop and in local development without a
-reverse-proxy rule. The redirect is temporary on purpose: browsers cache a
-`301` on the bare domain essentially forever, which would be painful to undo
-should `/` ever get real content. A shop that needs its own `/` defines
-`src/api/route.ts` itself.
+The modules and providers the base ships besides the platform, each with its
+own configuration, toggles and Admin surface.
 
-## Kunden-Login
+### Kunden-Login
 
 Module `customer_auth` (plugin key `customer_auth`, label "Kunden-Login")
 decides which login methods customers may use. The plugin cannot be switched
@@ -1218,233 +1407,57 @@ Storefront contract: DTOs, schemas and paths come from the Contracts package
 read `GET /store/plugin-features/customer_auth` and render only the enabled
 forms.
 
-## Password policy
+### E-Mail
 
-Medusa's `emailpass` provider accepts any non-empty password. The base runs a
-middleware on `POST /auth/:actor_type/emailpass/register` (customer sign-up,
-Admin invite) and `POST /auth/:actor_type/emailpass/update` (password reset).
-It is registered on `/auth/:actor_type/:auth_provider/:action` without
-`methods` and decides on the decoded, lowercased params, because Express
-matches literal path segments against the raw path: `/auth/customer/email%70ass/register`
-and `/auth/Customer/emailpass/register` reach Medusa's handler too, and
-`Customer` counts as the customer actor here.
-A password that breaks the rules of the actor is answered with
-`400 { type: "invalid_data", message }`; the one German message lists every
-unmet rule, e.g. `Das Passwort erfüllt nicht alle Regeln: mindestens 12
-Zeichen, eine Ziffer.` The check runs before Medusa's reset-token check, so a
-rejected password leaves the single-use reset link valid for a second attempt.
+The base owns transactional e-mail for the shop: logical email messages,
+attempts, rendering, the Medusa Notification integration, the SMTP and
+Microsoft 365 transports, retries and e-mail-specific Admin operations. It is
+the `email` module, its notification provider (`providers/smtp`, id `smtp`),
+its subscribers, jobs and
+workflows, and the Admin page `/settings/hartl-services/email`.
 
-**Admin users** (every actor type except `customer`) always need at least 15
-characters, counted as Unicode code points, and no composition rules. This
-follows NIST SP 800-63B Rev. 4 (the US guideline for digital identity) for a
-password that is the only factor.
+#### Configuration
 
-**Customers** follow the settings of the "Kunden-Login" plugin (group
-"Passwort-Regeln", Settings > "Hartl Services Plugins"). They apply only while
-`email_password` is on and take effect at once, without a cache:
+The notification provider is a `modules` entry built by
+`createEmailNotificationModuleConfig` (from
+`@hartl-services/medusa-base/config`); which service it sends through and the
+credentials are set in the Admin (see "Versand"). The branding and rendering
+configuration goes into the `email` namespace of the base options:
 
-| Key                           | Label                                | Default | Meaning |
-| ----------------------------- | ------------------------------------ | ------- | ------- |
-| `password_min_length`         | Mindestlänge                         | 15      | 8 to 128 characters, whole numbers only (`integer`); NIST SP 800-63B Rev. 4 recommends at least 15 when the password is the only factor |
-| `password_require_mixed_case` | Groß- und Kleinbuchstaben verlangen  | off     | at least one uppercase and one lowercase letter |
-| `password_require_digit`      | Ziffer verlangen                     | off     | at least one digit |
-| `password_require_symbol`     | Sonderzeichen verlangen              | off     | at least one punctuation mark or symbol (Unicode category P or S; whitespace, combining marks and invisible characters do not count) |
+```ts
+import { createEmailNotificationModuleConfig } from "@hartl-services/medusa-base/config";
 
-NIST SP 800-63B Rev. 4 advises against composition rules, because they lead to
-predictable passwords such as "Passwort1!"; a longer password protects better.
-The Admin texts say so. A missing or invalid stored value falls back to the
-default of that rule, and if the settings cannot be read at all the default
-policy (15 characters, no composition rules) applies and a warning is logged,
-so a registration is never blocked by a settings outage.
+export default defineConfig({
+  modules: [
+    createEmailNotificationModuleConfig({
+      // Permits "Verschlüsselung: Keine" (a local SMTP server); never in production.
+      allowInsecure:
+        process.env.NODE_ENV === "development" || process.env.NODE_ENV === "test",
+    }),
+  ],
+  plugins: [
+    {
+      resolve: "@hartl-services/medusa-base",
+      options: {
+        email: {
+          jwtSecret: process.env.JWT_SECRET!,
+          shop: {
+            displayName: "Mein Shop",
+            affiliatePortalUrl: "https://shop.example.com/de/partner",
+            inviteUrl: ({ token }) =>
+              `https://shop.example.com/app/invite?token=${token}`,
+            orderNotificationEmail: "orders@shop.example.com",
+            passwordResetUrl: ({ locale }) =>
+              `https://shop.example.com/${locale ?? "de"}/passwort-zuruecksetzen`,
+          }, // a ShopEmailConfiguration, see `ShopEmailConfiguration` in `@hartl-services/medusa-base/types`
+        },
+      },
+    },
+  ],
+});
+```
 
-**Route.** `GET /store/customer-auth/password-policy` (publishable key only)
-answers `{ password_policy: { min_length, require_mixed_case, require_digit,
-require_symbol } }`, the effective customer rules, and 404 while
-`email_password` is off. The storefront shows them in its forms and checks
-them with the same functions as the backend. The types, the path
-(`customerAuthStorePaths.get.passwordPolicy`) and the rules
-(`evaluatePasswordPolicy`, `isPasswordAllowed`, `DEFAULT_CUSTOMER_PASSWORD_POLICY`,
-`ADMIN_PASSWORD_POLICY` in `schemas/password-policy`) come from the Contracts
-package.
-
-**Admin passwords and the shared identity.** An `emailpass` identity is shared
-by all actor types: someone invited as an Admin could register through
-`/auth/customer/emailpass/register` with the (weaker) customer rules, log in at
-`/auth/user/emailpass` and accept the invite with that token, which would bind
-the weak password to an Admin. So the Admin login (`POST` and `GET`
-`/auth/user/emailpass`, decoded and lowercased like above) checks the body
-password against the Admin rules and answers the same `400` when the identity
-has no Admin yet (`app_metadata.user_id` unset). The login of an identity that
-already belongs to an Admin is never checked. Remaining limit, deliberately not
-closed: a customer could register through the Admin path with 15 characters and
-no composition rules although the shop asks for more; that only weakens their
-own password.
-
-Login of a customer is not checked, so existing passwords keep working until their next
-reset, whatever the rules are. Accounts created without HTTP (`medusa user`,
-seed scripts calling the Auth module) are not checked either.
-
-## Cart-promotion link repair
-
-Medusa's `deletePromotionsWorkflow` only soft-deletes a promotion and leaves
-its `cart_promotion` link rows behind, so every cart that had it applied
-reads back a `null` entry inside `cart.promotions`. The base removes those
-links itself:
-
-- The `deletePromotionsWorkflow.hooks.promotionsDeleted` hook
-  (`workflows/hooks/dismiss-deleted-promotion-cart-links`) dismisses the
-  links of the deleted promotions and restores them if a later step fails.
-- The migration script `dismiss-orphaned-cart-promotion-links` runs once in
-  `medusa db:migrate` and removes the links that already dangle from earlier
-  deletions. Medusa tracks migration scripts by file name in
-  `script_migrations`, so the name must not change.
-
-Nothing to configure; `medusa db:migrate` after installing or upgrading to
-0.4.1 is enough.
-
-## Draft orders and 0 € orders
-
-Draft orders (Medusa's `@medusajs/draft-order` plugin, loaded by default) are
-the shop's way to enter an order in the Admin: sample shipments, orders taken
-by phone, replacements. Item prices and the shipping amount are set directly
-in the draft; converting it never involves a payment provider.
-
-- **Customer order confirmation off by default.** The
-  `createOrderWorkflow.hooks.orderCreated` hook
-  (`workflows/hooks/draft-order-confirmation-default`) sets Medusa's
-  `no_notification` on every new draft, also when an API caller sent
-  `no_notification_order: false`. The Admin switches it per draft in the
-  **Bestellbestätigung** widget on the draft's detail page
-  (`GET`/`POST /admin/draft-orders/:id/order-confirmation`, see the E-Mail
-  "Admin API"). On conversion the `order-placed` subscriber records the
-  customer confirmation as `suppressed` (`notifications_disabled`); the copy
-  to the shop's order address is still sent. The shipment mail follows the
-  Admin's "notify customer" choice per shipment, not this switch.
-- **0 € orders count as paid.** Medusa derives an order's payment status from
-  its payment collections only, so a converted 0 € draft would stay
-  "Nicht bezahlt". The subscriber `order-zero-total-paid` runs
-  `order-mark-zero-total-paid` on `order.placed`: an order with a total of 0
-  and no payment collection gets a completed 0 € payment collection and reads
-  "Bezahlt" (`payment_status: captured`). Orders that already carry a
-  collection, i.e. every checkout order, are left alone. In SQL, a paid
-  order is one whose linked `payment_collection` (via
-  `order_payment_collection`) has `status = 'completed'`.
-
-Orders placed before installing this version keep their state.
-
-## Config helpers
-
-`@hartl-services/medusa-base/config` holds the generic environment helpers a
-shop's `medusa-config.ts` needs, so every shop fails at startup with the name
-of the missing variable instead of a runtime crash. The environment helpers
-have no dependency on Medusa; the subpath does not load `@sentry/node`.
-
-| Export | Purpose |
-|---|---|
-| `ConfigurationPhase` | `"build" \| "runtime"` |
-| `MEDUSA_BUILD_PLACEHOLDERS` | Placeholders for `ADMIN_CORS`, `AUTH_CORS`, `COOKIE_SECRET`, `DATABASE_URL`, `JWT_SECRET`, `MEDUSA_BACKEND_URL`, `STOREFRONT_URL`, `STORE_CORS`, `STRIPE_API_KEY`, `STRIPE_WEBHOOK_SECRET` |
-| `requireEnvironment(environment, names, phase, buildPlaceholders)` | Returns every named value (trimmed) or throws one error listing all missing names; in the build phase `buildPlaceholders` fill in for deployment values |
-| `optionalEnvironment`, `integerEnvironment`, `booleanEnvironment` | Trimmed optional string, range-checked integer, strict `"true"`/`"false"` boolean |
-| `allowsInsecureLocalServices(environment, phase)` | `true` for build, development and test |
-| `resolvePublicOrigin(value, name, allowHttp)`, `shopUrl(origin, path)` | Validate a bare HTTP(S) origin; build an absolute URL that cannot leave the origin |
-| `resolveStripe(values)` | Checks the `sk_` key and the `whsec_` webhook secret |
-| `resolveRedisEventBus(environment, phase)` | `{ url } \| undefined`: optional in development, required at runtime elsewhere, never used in a build, authenticated `rediss://` in production |
-| `createEmailNotificationModuleConfig`, `defineShopEmailConfiguration` (deprecated: `createSmtpNotificationModuleConfig`, `resolveSmtp`, `SMTP_ENVIRONMENT_VARIABLES`, `SMTP_BUILD_PLACEHOLDERS`) | Mail notification provider and E-Mail configuration (see "E-Mail") |
-| `createS3CacheStorageConfig`, `createS3CacheFileModuleConfig`, `resolveS3Credentials`, `resolveExpirationStrategy`, `S3_BUILD_PLACEHOLDERS` | S3 file storage (see "Dateispeicher (S3)") |
-| `createDefaultDocumentHtmlFactory`, `DOCUMENTS_BUILD_PLACEHOLDERS` | Documents markup and build placeholder (see "Dokumente") |
-
-`medusa build` loads the configuration without deployment secrets. Each
-plugin's own placeholders (SMTP, S3, PDF executable, ...) live with that
-plugin; the shop merges them:
-
-```ts
-// medusa-config.ts
-import {
-  MEDUSA_BUILD_PLACEHOLDERS,
-  requireEnvironment,
-  resolveRedisEventBus,
-  type ConfigurationPhase,
-} from "@hartl-services/medusa-base/config"
-
-const phase: ConfigurationPhase =
-  process.env.MEDUSA_BUILD_PHASE === "true" ? "build" : "runtime"
-const env = requireEnvironment(
-  process.env,
-  ["DATABASE_URL", "JWT_SECRET", "COOKIE_SECRET"],
-  phase,
-  { ...MEDUSA_BUILD_PLACEHOLDERS /* , ...other plugins' placeholders */ },
-)
-const redis = resolveRedisEventBus(process.env, phase)
-```
-
-## Sentry instrumentation
-
-`@hartl-services/medusa-base/instrumentation` exports `register()`, the hook
-Medusa's start command calls from the shop's `instrumentation.ts`. It runs
-`Sentry.init` with `SENTRY_DSN`, `SENTRY_ENVIRONMENT` (fallback `NODE_ENV`)
-and `tracesSampleRate: 0`; without a `SENTRY_DSN` Sentry stays inert. The
-shop's `instrumentation.ts` is one line:
-
-```ts
-export { register } from "@hartl-services/medusa-base/instrumentation"
-```
-
-`@sentry/node` stays an optional peer dependency of the base: a shop that uses
-this export (or `sentry-logger`) lists `@sentry/node` in its own
-`dependencies`.
-
-## E-Mail
-
-The base owns transactional e-mail for the shop: logical email messages,
-attempts, rendering, the Medusa Notification integration, the SMTP and
-Microsoft 365 transports, retries and e-mail-specific Admin operations. It is
-the `email` module, its notification provider (`providers/smtp`, id `smtp`),
-its subscribers, jobs and
-workflows, and the Admin page `/settings/hartl-services/email`. There is no
-separate e-mail package since 1.0.0.
-
-### Configuration
-
-The notification provider is a `modules` entry built by
-`createEmailNotificationModuleConfig` (from
-`@hartl-services/medusa-base/config`); which service it sends through and the
-credentials are set in the Admin (see "Versand"). The branding and rendering
-configuration goes into the `email` namespace of the base options:
-
-```ts
-import { createEmailNotificationModuleConfig } from "@hartl-services/medusa-base/config";
-
-export default defineConfig({
-  modules: [
-    createEmailNotificationModuleConfig({
-      // Permits "Verschlüsselung: Keine" (a local SMTP server); never in production.
-      allowInsecure:
-        process.env.NODE_ENV === "development" || process.env.NODE_ENV === "test",
-    }),
-  ],
-  plugins: [
-    {
-      resolve: "@hartl-services/medusa-base",
-      options: {
-        email: {
-          jwtSecret: process.env.JWT_SECRET!,
-          shop: {
-            displayName: "Mein Shop",
-            affiliatePortalUrl: "https://shop.example.com/de/partner",
-            inviteUrl: ({ token }) =>
-              `https://shop.example.com/app/invite?token=${token}`,
-            orderNotificationEmail: "orders@shop.example.com",
-            passwordResetUrl: ({ locale }) =>
-              `https://shop.example.com/${locale ?? "de"}/passwort-zuruecksetzen`,
-          }, // a ShopEmailConfiguration, see `ShopEmailConfiguration` in `@hartl-services/medusa-base/types`
-        },
-      },
-    },
-  ],
-});
-```
-
-Options of the `email` namespace:
+Options of the `email` namespace:
 
 - `jwtSecret` — used for Email's own tokens; typically the same secret as
   `projectConfig.http.jwtSecret`.
@@ -1455,7 +1468,7 @@ Options of the `email` namespace:
   that confirms an account, needed while `customer_verification` is on.
   `adminPasswordResetUrl` (optional builder, receives `{ token }`) is the
   Medusa Admin's "choose a new password" page; without it an Admin user's
-  password reset fails with `render_failed`. `buildFoodShopConfig` sets
+  password reset fails with `render_failed`. `buildShopConfig` sets
   `<MEDUSA_BACKEND_URL>/app/reset-password?token=<token>` (the dashboard reads
   the token from the query).
   `adminAffiliateApplicationsUrl` (optional builder, receives
@@ -1472,22 +1485,17 @@ fact only while the Documents `invoices` feature is on when the message is
 created (with `invoices` off, or the Documents plugin switched off, Documents
 publishes no fact, so the mail is sent without a document). Refund e-mails
 come only from the Documents refund fact, so there are none while `invoices`
-is off. The former `documentsEnabled` option no longer exists: Documents is
-always part of the base.
+is off.
 
 The event contracts the module consumes for shipment, cancellation, refund and
 affiliate-reminder and partner-application e-mails come from
-`@hartl-services/medusa-food-supplements-contracts/events/documents` and
+`@hartl-services/medusa-contracts/events/documents` and
 `/events/affiliate`, so installing the base does not pull in Affiliate.
 
 The provider reads no environment variables (since 2.9.0; the former
 `SMTP_*` variables are ignored).
 
-Set `REDIS_URL` to use `@medusajs/event-bus-redis` instead of Medusa's local
-Event Bus; production requires an authenticated `rediss://` URL. See "Event
-Bus" below for retry/backoff behavior.
-
-### Versand
+#### Versand
 
 The page E-Mail → "Versand" (`/settings/hartl-services/email/delivery`, linked
 under "Verwaltung") edits the plugin's settings. It stays reachable while the
@@ -1547,7 +1555,7 @@ to the e-mail of the Shop-Stammdaten, once per client id and expiry date (a
 log warning when the Shop-Stammdaten have no e-mail). A new secret with a new
 date warns again.
 
-### Feature toggles
+#### Feature toggles
 
 The E-Mail module declares its toggles to `@hartl-services/medusa-base` under the
 plugin key `email`. An Admin switches them under Settings → "Hartl Services
@@ -1583,7 +1591,7 @@ rows are dimmed and their switches disabled then. All E-Mail sub-pages
 switch and show `PluginFeatureDisabledNotice` while it is off (the backend
 answers `404` for `/admin/email/*` then).
 
-### Kontobestätigung per E-Mail
+#### Kontobestätigung per E-Mail
 
 Feature `customer_verification` (child of `account_mails`, default **off**)
 makes customers confirm their e-mail address through a link before their
@@ -1658,11 +1666,12 @@ the toggle itself and follow at once. A failed read keeps the last value and
 logs a warning; before the first successful read the copy is off. The copy
 lives on `globalThis` because the preset (`dist`) and the plugin code Medusa
 loads (`.medusa/server`) are compiled separately. Only the preset
-(`buildFoodShopConfig` / `defineFoodShopConfig`) sets the getter; a shop with a
+(`buildShopConfig` / `defineShopConfig`) sets the getter; a shop with a
 hand-written config must set `authVerificationsPerActor` itself (a fixed list,
 changed by a restart) for the toggle to have any effect on logins.
 
-Login is not on the cart path, so the cart rule above is not affected.
+Login is not on the cart path, so the rule in "Never on the cart path" is
+not affected.
 
 Things to know when switching it on:
 
@@ -1688,7 +1697,7 @@ Storefront contract (DTOs, schema and path from the Contracts package,
 - Serve `/<cc>/verify-account`, read `token` from `location.hash`, confirm it
   and then send the customer to the login.
 
-### Ownership
+#### Ownership
 
 - Documents owns document issuance and publishes immutable document facts.
 - Affiliate owns reminder eligibility and publishes reminder and application
@@ -1697,14 +1706,14 @@ Storefront contract (DTOs, schema and path from the Contracts package,
   status plus the attachment library (documents with append-only PDF
   versions).
 - Public HTTP DTOs, schemas, and paths remain in
-  `@hartl-services/medusa-food-supplements-contracts`.
+  `@hartl-services/medusa-contracts`.
 
 The base's `/types` and `/config` exports are dedicated server integration
 surfaces for the backend. The Documents and Affiliate event contracts live in
 the Contracts package (`events/documents`, `events/affiliate`). The base exports no DML models, services,
 workflows, migrations, or generated output as a consumer contract.
 
-### Event Bus
+#### Event Bus
 
 The backend owns Event Bus selection. Development without `REDIS_URL` leaves
 Medusa's local Event Bus active. Configuring `REDIS_URL` registers
@@ -1718,7 +1727,7 @@ for at most one hour and 1,000 entries. There is no custom Event Bus wrapper,
 startup capability probe, or purge job. Events are at-least-once facts and can
 be replayed, delayed, or delivered out of order.
 
-### Event Contracts
+#### Event Contracts
 
 All payload objects are strict. Unless noted otherwise, every string shown
 below is trimmed and non-empty. Native event names and shapes are fixed to the
@@ -1844,7 +1853,7 @@ concurrent request never sends a second mail) addressed to
 `affiliate-consignment:<affiliate_id>:<period_start>`. `locale`, when present,
 has at most 35 characters. Email runtime-validates every contract before use.
 
-### Invariants
+#### Invariants
 
 - The accepted kinds are exactly `order.received`, `order.received.admin`, `order.shipped`,
   `order.canceled`, `order.return_requested`, `order.return_received`,
@@ -1898,7 +1907,7 @@ has at most 35 characters. Email runtime-validates every contract before use.
 
 Read this section and the central design before changing Email domain behavior.
 
-### Shop configuration and default templates
+#### Shop configuration and default templates
 
 The E-Mail module ships a neutral German layout in grey tones (table-based,
 inline styles) and one renderer per accepted kind; the colors of the
@@ -1935,7 +1944,7 @@ an info box lists number, customer, e-mail and order time, followed by an
 "Im Admin öffnen" button and the items, totals and addresses. Two optional
 `ShopEmailConfiguration` fields drive it: `adminOrderUrl({ orderId })` (the
 button is left out without it) and `timeZone` (IANA; the order time is left
-out without it). `buildFoodShopConfig` sets both (`<MEDUSA_BACKEND_URL>/app/
+out without it). `buildShopConfig` sets both (`<MEDUSA_BACKEND_URL>/app/
 orders/<id>` and its `timeZone` option). The layout receives `audience`
 (`"shop"` for this kind, `affiliate.application_submitted.admin`, `system.credential_expiry.admin`, `user.invite` and `auth.admin_password_reset`, `"customer"` for all others) and
 shows the contact line only to customers.
@@ -2047,7 +2056,7 @@ Partner-Bewerbung von <Firma>" (without a company the applicant's name, then
 the e-mail address; just "Neue Partner-Bewerbung" if none is known). An info
 box lists company, name and e-mail (only the present ones), the applicant's
 message follows as an escaped paragraph, and an "Im Admin prüfen" button links
-`adminAffiliateApplicationsUrl` (left out without it; `buildFoodShopConfig`
+`adminAffiliateApplicationsUrl` (left out without it; `buildShopConfig`
 sets `<MEDUSA_BACKEND_URL>/app/affiliates/applications`). Its layout audience
 is `"shop"`. All applicant text is HTML-escaped.
 
@@ -2084,7 +2093,7 @@ configuration (blank `displayName`, a non-function `layout` or renderer, an
 unknown renderer kind) fails at startup and not at the first send. Custom
 renderers must escape dynamic values in `bodyHtml` themselves.
 
-### Deprecated SMTP helpers
+#### Deprecated SMTP helpers
 
 `createSmtpNotificationModuleConfig(smtp)`, `resolveSmtp`,
 `SMTP_ENVIRONMENT_VARIABLES` and `SMTP_BUILD_PLACEHOLDERS` remain exported
@@ -2093,7 +2102,7 @@ given to `createSmtpNotificationModuleConfig` only fill SMTP settings that are
 not stored in the Admin (the Admin status does not count them as configured).
 Use `createEmailNotificationModuleConfig` and the "Versand" page instead.
 
-### Delivery Semantics
+#### Delivery Semantics
 
 For ordinary durable messages, only characterized connection failures,
 temporary SMTP rejections, and temporary attachment access failures are
@@ -2119,7 +2128,7 @@ data remain ephemeral; both kinds are excluded from the generic retry job and
 Admin resend, and retryable handling stays bounded by the original Event Bus
 event.
 
-### Admin API
+#### Admin API
 
 Email exposes authenticated Admin operations at:
 
@@ -2190,7 +2199,7 @@ a different UUID represents a separate, conscious Admin decision. The Admin UI
 therefore retains a UUID while retrying an ambiguous failed request and creates
 a new UUID only after a new confirmation.
 
-### Admin UI
+#### Admin UI
 
 The E-Mail module has an Admin area under `/settings/hartl-services/email`
 (**Settings → Hartl Services Plugins → E-Mail → Öffnen**; the descriptor's
@@ -2239,7 +2248,7 @@ request UUID; downloads use the configured authenticated Admin SDK and never
 expose storage file IDs or URLs in the UI. There is no delete: removing every
 assigned mail lets a document rest.
 
-### Mail templates
+#### Mail templates
 
 All 13 mails (`EMAIL_EDITABLE_KINDS`) are block templates an Admin edits
 from the group pages of the E-Mail area (Bestell-, Konto- and Affiliate-Mails
@@ -2340,7 +2349,7 @@ and then each changed mail kind on its own.
     bzw. ist beschädigt.“), any other read failure „Anhang „X“ konnte
     gerade nicht geladen werden.“
 
-### Mail attachments
+#### Mail attachments
 
 The global Terms PDFs (`AGB`), the EU legal-guarantee notice or a flyer are
 documents of the attachment library. A document has a name, the customer
@@ -2355,8 +2364,8 @@ Admin consumers import wire DTOs and paths only from the Contracts package and
 reuse their configured Medusa SDK:
 
 ```ts
-import type { ListAdminEmailMessagesResponse } from "@hartl-services/medusa-food-supplements-contracts/types/email-admin";
-import { emailAdminPaths } from "@hartl-services/medusa-food-supplements-contracts/paths/email";
+import type { ListAdminEmailMessagesResponse } from "@hartl-services/medusa-contracts/types/email-admin";
+import { emailAdminPaths } from "@hartl-services/medusa-contracts/paths/email";
 
 const response = await sdk.client.fetch<ListAdminEmailMessagesResponse>(
   emailAdminPaths.get.list,
@@ -2366,15 +2375,11 @@ const response = await sdk.client.fetch<ListAdminEmailMessagesResponse>(
 Do not import E-Mail module implementations, generated `.medusa` files, or
 duplicate runtime schemas in an Admin consumer. The base's own exports remain
 internal server and generated Admin integration surfaces; Email HTTP contracts
-are published only by `@hartl-services/medusa-food-supplements-contracts`.
+are published only by `@hartl-services/medusa-contracts`.
 
-### Development and Rollout
+#### Rollout
 
-For local development, provide the seven SMTP variables and omit `REDIS_URL` to
-use Medusa's local Event Bus. Set `REDIS_URL` only when intentionally exercising
-the direct Redis provider. The backend HTTP runner ignores ambient Redis and
-SMTP settings and injects an isolated Redis container, unique queue, and
-token-protected SMTP fixture for every child.
+Local development notes: see "Development".
 
 This architecture replaces the old Documents and Affiliate delivery baselines
 without a backfill or compatibility layer. Existing local databases from those
@@ -2390,7 +2395,7 @@ production business data exists; a populated database requires a separately
 reviewed migration. No old delivery rows or queued jobs are migrated or purged
 by Email.
 
-## Dokumente
+### Dokumente
 
 The base issues order documents: one total invoice per order after the final
 shipment and one negative cancellation document for each eligible payment
@@ -2398,10 +2403,9 @@ refund. An Admin user can regenerate issued documents in place for exceptional
 corrections. The base ships default German document markup, so a new shop needs
 no template code; a project can optionally replace the HTML/CSS factory. PDF
 generation, private file storage, customer authorization and durable
-document-readiness facts stay inside the `documents` module. There is no
-separate documents package since 1.0.0.
+document-readiness facts stay inside the `documents` module.
 
-### What it does
+#### What it does
 
 - Listens to Medusa's `shipment.created` event.
 - Creates an invoice only if the order is fully shipped and not cancelled.
@@ -2468,7 +2472,7 @@ separate documents package since 1.0.0.
 - Reconciles non-canceled physical fulfillments periodically so a lost local
   event can be repaired idempotently, including after shipment.
 
-### Configuration
+#### Configuration
 
 The invoice workflow reads the order's frozen B2B evidence from the base's own
 `tax_compliance` module (see "Steuer-Compliance"); register the Tax provider
@@ -2527,7 +2531,7 @@ The `documents` module is always registered with the base (no `documentsEnabled`
 switch); the Admin switches it off at run time through the feature toggles
 below. `medusa db:migrate` creates its tables.
 
-### The `/config` subpath
+#### The `/config` subpath
 
 `@hartl-services/medusa-base/config` exports, next to the environment helpers,
 build-time values for `medusa-config.ts` and tests:
@@ -2542,7 +2546,7 @@ build-time values for `medusa-config.ts` and tests:
 The document types (`DocumentMerchantOption`, `DocumentHtmlFactory`,
 `DocumentRenderInput`, ...) come from `@hartl-services/medusa-base/types`.
 
-### Layout, logo, payment terms and shop theme
+#### Layout, logo, payment terms and shop theme
 
 The default markup prints an A4 letterhead: logo top left, document title and
 key data (number, order, date, customer UID for exempt B2B supplies) on the
@@ -2585,7 +2589,7 @@ fonts as `data:` URLs; the container's Chromium has only its system fonts. A
 shop passes its factory through the preset option `documentHtmlFactory` (see
 "Shop-Config-Preset").
 
-### Merchant data
+#### Merchant data
 
 The legal sender printed on every document comes from the base plugin's shop
 master data (Admin → Settings → Hartl Services Plugins → **Shop-Stammdaten**).
@@ -2617,7 +2621,7 @@ Requirements/couplings:
 - The Tax provider `tp_tax_compliance` of the base's Steuer-Compliance on the
   regions, so orders carry UID-based exemptions.
 - A Chromium/Chrome executable and a Medusa File provider that supports
-  private files (see "Development" below for the sandbox/non-root note).
+  private files (see "Shop integration" below for the sandbox/non-root note).
   Documents stores PDFs through `Modules.FILE` and streams them only through
   its own authenticated routes, so it works with any File provider and does
   not need the S3 file storage or its `/files` routes.
@@ -2633,8 +2637,7 @@ Requirements/couplings:
   batch/lot data on invoices and packing lists (see "Optional Batch
   Management integration" below).
 
-
-### Feature toggles
+#### Feature toggles
 
 The Documents module declares its toggles to the base under the plugin key
 `documents`. An Admin switches them under Settings → "Hartl
@@ -2672,15 +2675,14 @@ using `PluginFeatureGate` from
 No workflow hook and nothing on the cart, checkout or fulfillment path reads
 a toggle.
 
-### Shop integration
+#### Shop integration
 
 The demo shop (`apps/backend`) gets everything from the preset (see
 "Shop-Config-Preset"): `documents.numbering.timeZone` is its `timeZone`
 option, `documents.htmlFactory` its optional `documentHtmlFactory` and
 `documents.pdf.executablePath` the `DOCUMENT_PDF_EXECUTABLE` variable. The
-development UID `ATU00000000` is a placeholder: Documents never prints it,
-and Tax Compliance does not transmit it to FinanzOnline. Enter the real
-merchant UID in the Shop-Stammdaten before issuing production invoices.
+development UID `ATU00000000` is a placeholder that Documents never prints
+(see "UID check in the checkout").
 
 `htmlFactory` is intentionally the only presentation extension point. It gets
 a fully typed value snapshot (`DocumentTemplateInput` or
@@ -2698,7 +2700,7 @@ directory and removes it afterward. The Chromium child is also disconnected
 from the user's session bus and legacy keyring socket, so it cannot access the
 operator's normal browser profile or desktop keyring, including under WSLg.
 
-### Restore check for private files
+#### Restore check for private files
 
 After restoring the object store (or the local file directory), check that
 every issued document's PDF can be read through the active Medusa File
@@ -2712,7 +2714,7 @@ pnpm exec medusa exec ./node_modules/@hartl-services/medusa-base/.medusa/server/
 It fails on the first issued document without a stored file and otherwise
 logs the number of verified files and bytes.
 
-### Clean baseline and first deployment
+#### Clean baseline and first deployment
 
 The module intentionally contains one generated eight-table baseline,
 `Migration20260827061749`. It removes the former `documents_delivery` table
@@ -2758,7 +2760,7 @@ Apply normal pending module migrations after later changes or upgrades with
 does not require link synchronization by itself; `db:sync-links` above is the
 safe shop-wide first-deployment step for links owned elsewhere.
 
-### Storefront contract
+#### Storefront contract
 
 All three endpoints require a customer session or bearer token. There is no
 guest lookup endpoint and no direct File-provider URL.
@@ -2774,8 +2776,8 @@ address/email, file and artifact IDs, leases and resolution state.
 For a typed Storefront integration:
 
 ```ts
-import type { ListStoreDocumentsResponse } from "@hartl-services/medusa-food-supplements-contracts/types/documents-store";
-import { documentsPaths } from "@hartl-services/medusa-food-supplements-contracts/paths/documents";
+import type { ListStoreDocumentsResponse } from "@hartl-services/medusa-contracts/types/documents-store";
+import { documentsPaths } from "@hartl-services/medusa-contracts/paths/documents";
 
 const { documents: issuedDocuments } =
   await sdk.client.fetch<ListStoreDocumentsResponse>(
@@ -2791,13 +2793,13 @@ storage URL.
 
 The same Contracts boundary applies to all Documents and Tax Compliance public
 routes: import transport DTOs only from
-`@hartl-services/medusa-food-supplements-contracts/types/<feature>`, paths only from
-`@hartl-services/medusa-food-supplements-contracts/paths/<feature>`, and call the
+`@hartl-services/medusa-contracts/types/<feature>`, paths only from
+`@hartl-services/medusa-contracts/paths/<feature>`, and call the
 Storefront's configured Medusa SDK. A consumer that needs a runtime guard may
-opt in to `@hartl-services/medusa-food-supplements-contracts/schemas/<feature>`; it must
+opt in to `@hartl-services/medusa-contracts/schemas/<feature>`; it must
 not import either the plugin implementation or generated `.medusa` output.
 
-### Admin order detail
+#### Admin order detail
 
 When Documents is enabled, the Medusa Admin order detail shows a
 **Dokumente** widget. It lists the issued documents for that order (kind and
@@ -2817,7 +2819,7 @@ The Admin API is deliberately scoped by both order and document ID:
 All authenticated Admin users can inspect order documents; a document from a
 different order returns `404` from the download endpoint.
 
-#### Internal packing lists
+##### Internal packing lists
 
 The separate **Packlisten** order widget lists every physical fulfillment in
 creation order, each with a status badge (Nicht erstellt, Ausstehend, Wird
@@ -2841,7 +2843,7 @@ Packing lists never pass through the Documents customer-fact pipeline. They are
 also stored outside `documents_document`, so the authenticated Store document
 queries cannot expose them accidentally.
 
-#### Regenerating an invoice
+##### Regenerating an invoice
 
 The widget offers **Rechnung ausstellen** only while the order has no
 invoice; once one exists, every document row has a regenerate icon button
@@ -2862,7 +2864,7 @@ above. A cancellation or future credit note is instead rendered from its
 persisted snapshot, retaining its original amount, source invoice reference,
 number and issue date. It also emits no customer communication event.
 
-#### Financial document numbers
+##### Financial document numbers
 
 Documents assigns numbers in these annual ranges:
 
@@ -2885,7 +2887,7 @@ increments a range. A permanently failed document retains its number and
 failure reason as the explanation for that range's gap; reserved numbers are
 never recycled or reassigned.
 
-#### Cancellation documents for payment refunds
+##### Cancellation documents for payment refunds
 
 Medusa's refund event identifies the payment, so the plugin enumerates its
 persisted refund records and claims one cancellation document using each
@@ -2907,7 +2909,7 @@ not create a second customer fact. For a canceled Order, individual Refund
 facts are suppressed in favor of the authoritative Order-cancellation
 resolution and its sorted artifact list.
 
-### Optional Batch Management integration
+#### Optional Batch Management integration
 
 If `@hartl-services/medusa-batch-management` version `0.0.3` or later is registered, Documents detects
 its `getOrderDocumentBatchSnapshot(orderId)` capability structurally. For every
@@ -2938,11 +2940,11 @@ list revision and serves the newest ready PDF. Returns do not rewrite the
 historical pick instruction. Fulfillment cancellation marks the packing list as
 canceled and prevents a concurrent render from being published as active.
 
-### Document facts and artifacts
+#### Document facts and artifacts
 
 Documents owns no Notification or delivery state. Its integration boundary is
 the strict versioned event contract exported from
-`@hartl-services/medusa-food-supplements-contracts/events/documents`. Shipment assignments, standalone Refund resolutions and Order-
+`@hartl-services/medusa-contracts/events/documents`. Shipment assignments, standalone Refund resolutions and Order-
 cancellation resolutions each carry an `event_emitted_at` marker that is set
 only after successful enqueue.
 
@@ -2959,10 +2961,10 @@ worker has lost its lease, the unreferenced private File is deleted best-effort;
 a hard process exit in that external File/database gap can leave a storage
 orphan but cannot commit another Artifact, carrier or resolution.
 
-#### Exact outgoing event contracts
+##### Exact outgoing event contracts
 
 The server-only Contracts subpath
-`@hartl-services/medusa-food-supplements-contracts/events/documents` exports the
+`@hartl-services/medusa-contracts/events/documents` exports the
 event-name constants,
 strict Zod schemas and inferred payload types for exactly these three events:
 
@@ -3043,8 +3045,6 @@ before the process can persist success, so an ambiguous attempt becomes
 `unknown` and is not automatically sent again. Any later resend is an explicit
 Email Admin action and a new logical message.
 
-### Development
-
 #### Public Storefront and Admin contracts
 
 The central contracts package exports the Documents Store and Admin DTOs, Zod
@@ -3052,8 +3052,8 @@ schemas and route paths, but no second Storefront client. Consumers use their
 own Medusa SDK instance:
 
 ```ts
-import type { GetStoreDocumentResponse } from "@hartl-services/medusa-food-supplements-contracts/types/documents-store";
-import { documentsPaths } from "@hartl-services/medusa-food-supplements-contracts/paths/documents";
+import type { GetStoreDocumentResponse } from "@hartl-services/medusa-contracts/types/documents-store";
+import { documentsPaths } from "@hartl-services/medusa-contracts/paths/documents";
 
 const response = await sdk.client.fetch<GetStoreDocumentResponse>(
   documentsPaths.store.get.retrieve(documentId),
@@ -3061,10 +3061,10 @@ const response = await sdk.client.fetch<GetStoreDocumentResponse>(
 );
 ```
 
-`@hartl-services/medusa-food-supplements-contracts/types/documents-store` and
-`@hartl-services/medusa-food-supplements-contracts/types/documents-admin` contain the
+`@hartl-services/medusa-contracts/types/documents-store` and
+`@hartl-services/medusa-contracts/types/documents-admin` contain the
 respective type-only DTOs. Import
-`@hartl-services/medusa-food-supplements-contracts/schemas/documents` only for explicit
+`@hartl-services/medusa-contracts/schemas/documents` only for explicit
 runtime validation. The common Storefront case imports only types, which are
 erased by TypeScript, and the path module; it never imports the plugin's Medusa
 server code. Store and Admin responses use the same safe `DocumentSummary`
@@ -3076,8 +3076,8 @@ and README note together when introducing another Documents route.
 Packing-list consumers stay Admin-only:
 
 ```ts
-import type { ListAdminOrderPackingListsResponse } from "@hartl-services/medusa-food-supplements-contracts/types/documents-admin";
-import { packingListsPaths } from "@hartl-services/medusa-food-supplements-contracts/paths/documents";
+import type { ListAdminOrderPackingListsResponse } from "@hartl-services/medusa-contracts/types/documents-admin";
+import { packingListsPaths } from "@hartl-services/medusa-contracts/paths/documents";
 
 const response = await sdk.client.fetch<ListAdminOrderPackingListsResponse>(
   packingListsPaths.admin.get.listForOrder(orderId),
@@ -3085,16 +3085,15 @@ const response = await sdk.client.fetch<ListAdminOrderPackingListsResponse>(
 );
 ```
 
-## Steuer-Compliance
+### Steuer-Compliance
 
-There is no separate `@hartl-services/medusa-tax-compliance` package since
-3.0.0: the EU tax compliance (module `tax_compliance`, the Tax Module provider
+The EU tax compliance (module `tax_compliance`, the Tax Module provider
 `tp_tax_compliance`, the UID check routes, the order-evidence freeze and the
-apportioned shipping tax) is part of the base. The module owns the durable
-validation evidence; a Storefront never imports its implementation, only
-`@hartl-services/medusa-food-supplements-contracts`.
+apportioned shipping tax) is part of the base since 3.0.0 (see "Upgrading").
+The module owns the durable validation evidence; a Storefront never imports
+its implementation, only `@hartl-services/medusa-contracts`.
 
-### Configuration
+#### Configuration
 
 Register the Tax Module provider in `medusa-config.ts` (the Shop-Config-Preset
 does this); the module itself boots with the base and has no options:
@@ -3124,7 +3123,7 @@ The merchant's own country and VAT number come only from the Shop-Stammdaten
 select the qualified VAT validator (currently only the Austrian FinanzOnline
 adapter). While either is missing, carts get ordinary B2C tax.
 
-### Runtime settings
+#### FinanzOnline settings
 
 Declared on the Steuer-Compliance descriptor and edited on its Admin page
 (Settings → Hartl Services Plugins → Steuer-Compliance):
@@ -3175,7 +3174,7 @@ qualifizierte UID-Abfrage.").
   answers ordinary B2C rates. The order tax path needs no merchant: it checks
   the evidence frozen under the order ID.
 
-### Feature toggles
+#### Feature toggles
 
 Steuer-Compliance declares its switch and three features under the plugin key
 `tax_compliance` (`TAX_COMPLIANCE_PLUGIN_KEY` / `TAX_COMPLIANCE_FEATURES` from
@@ -3214,14 +3213,14 @@ values; the `plugin-features.updated.v1` subscriber and the
 sync (no row) both count as on; when the row cannot be read both count as
 off (ordinary B2C rates, Medusa's shipping tax).
 
-### UID check in the checkout
+#### UID check in the checkout
 
 Public Store request, response, schema, and path imports belong to
-`@hartl-services/medusa-food-supplements-contracts`:
+`@hartl-services/medusa-contracts`:
 
 ```ts
-import type { SubmitTaxIdentificationResponse } from "@hartl-services/medusa-food-supplements-contracts/types/tax-compliance-store";
-import { taxCompliancePaths } from "@hartl-services/medusa-food-supplements-contracts/paths/tax-compliance";
+import type { SubmitTaxIdentificationResponse } from "@hartl-services/medusa-contracts/types/tax-compliance-store";
+import { taxCompliancePaths } from "@hartl-services/medusa-contracts/paths/tax-compliance";
 
 const result = await sdk.client.fetch<SubmitTaxIdentificationResponse>(
   taxCompliancePaths.store.carts.taxIdentification(cartId),
@@ -3310,8 +3309,8 @@ GET /store/tax-identification-policy   →   { merchant_country_code: "at" | nul
 storefront then asks for every country.
 
 ```ts
-import type { GetTaxIdentificationPolicyResponse } from "@hartl-services/medusa-food-supplements-contracts/types/tax-compliance-store";
-import { taxCompliancePaths } from "@hartl-services/medusa-food-supplements-contracts/paths/tax-compliance";
+import type { GetTaxIdentificationPolicyResponse } from "@hartl-services/medusa-contracts/types/tax-compliance-store";
+import { taxCompliancePaths } from "@hartl-services/medusa-contracts/paths/tax-compliance";
 
 const { merchant_country_code } = await sdk.client.fetch<GetTaxIdentificationPolicyResponse>(
   taxCompliancePaths.store.taxIdentificationPolicy,
@@ -3324,7 +3323,7 @@ gets 3 s, so the request stays below a storefront's 15 s checkout wait and the
 database transaction holding the UID lock never waits on a hanging
 FinanzOnline call; a timeout answers `unavailable` (`technical_error`).
 
-### Saved customer addresses
+#### Saved customer addresses
 
 A saved customer address carries its UID in `metadata.vat_number`
 (`TAX_IDENTIFICATION_METADATA_KEY` in the Contracts). A logged-in customer
@@ -3372,7 +3371,7 @@ facts likewise receive ordinary B2C tax, without a warning. The registry is
 country-based: it currently provides only the Austrian FinanzOnline adapter;
 an unsupported merchant country deliberately resolves to `unavailable`.
 
-### Frozen order evidence
+#### Frozen order evidence
 
 Cart tax workflows pass only the opaque current evidence ID and the merchant
 profile (country and UID) to the provider. Order tax workflows use evidence
@@ -3401,19 +3400,104 @@ wording from the completed order (see "Dokumente"). A later cart change or
 validation cannot alter an already issued document; B2C, invalid, ineligible
 and unavailable evidence adds no tax-proof wording.
 
-## Dateispeicher (S3)
+### Versandkostenfrei
+
+The shop-wide free-shipping threshold with a separate threshold for
+affiliates is part of the base since 5.0.0 (module `free_shipping`, see
+"Upgrading"). It has no Admin page and no HTTP route of its own: its switch
+and its settings are edited on the generic plugin page **Settings → Hartl
+Services Plugins → Versandkostenfrei**
+(`/settings/hartl-services/plugin/free_shipping`).
+
+#### What it does
+
+- Keeps two automatic Medusa promotions (`AUTO-FREE-SHIPPING-STANDARD`,
+  `AUTO-FREE-SHIPPING-AFFILIATE`, 100 % off shipping) in sync with the
+  settings and the plugin switch:
+  - right after the settings are saved in the Admin
+    (`plugin-settings.updated.v1` subscriber),
+  - right after the switch is changed in the Admin
+    (`plugin-features.updated.v1` subscriber),
+  - every 15 minutes through the `free-shipping-promotion-sync` scheduled job
+    (worker instances only), which also repairs drift and covers a lost event.
+
+  Every run holds one Locking-module lock (`free-shipping-promotion-sync`,
+  60 s timeout) around the whole sync, so the job and the two subscribers never
+  interleave their rule changes, and the last run always writes the latest
+  values. The shop's configured Locking provider applies (Medusa's default
+  in-memory provider serializes within one process only; use a shared
+  provider such as `@medusajs/locking-redis` when server and worker are
+  separate processes). The sync writes only differences, so a run against
+  in-sync promotions is read-only. Changed rules are created before outdated
+  ones are deleted, so an automatic promotion never exists without its rules
+  (which would grant free shipping to every cart).
+- Adds the cart's affiliate qualification to the promotion context (hook on
+  `updateCartPromotionsWorkflow`). This uses the `affiliate` module only if it
+  is registered (`tryResolveOptional`); without the Affiliate plugin, only the
+  default threshold applies.
+
+#### Settings
+
+Stored in `plugin_setting_state` under the plugin key `free_shipping`; every
+setting has a default, so the feature works without ever saving the page.
+
+| Key                                       | Type    | Default | Label                                                                    | Effect                                                                                  |
+| ----------------------------------------- | ------- | ------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
+| `default_threshold`                       | number ≥ 0 | 50   | Kostenlose Lieferung ab (€)                                              | `item_total` threshold of `AUTO-FREE-SHIPPING-STANDARD`                                  |
+| `affiliate_threshold`                     | number ≥ 0 | 100  | Für Affiliates ab (€)                                                    | `item_total` threshold of `AUTO-FREE-SHIPPING-AFFILIATE`                                 |
+| `affiliate_applies_to_account_holders`    | boolean | on      | Gilt, wenn der Kunde selbst Affiliate ist                                | the cart's customer is an affiliate → affiliate threshold                                |
+| `affiliate_applies_to_referred_customers` | boolean | off     | Gilt, wenn der Warenkorb über einen Affiliate-Link oder -Code zugeordnet wurde | the cart is assigned to an affiliate referral → affiliate threshold                       |
+
+The base validates the values (a negative threshold is rejected with 400).
+Server code reads them with `resolveFreeShippingSettings(container)`
+(`src/free-shipping/free-shipping-settings.ts`, a typed wrapper around
+`getPluginSettings`). The two boolean rules are evaluated in the cart hook on
+every promotion computation, so they take effect without a promotion resync;
+the thresholds reach the promotions through the sync described above.
+
+The cart hook is fail-safe: if the settings cannot be read, the error is
+reported with `logger.error` (forwarded to Sentry by the logger wrapper) and
+the cart is computed with the two rules this process last read successfully,
+or with their declared defaults (account holders on, referred customers off)
+when it has not read them yet. The cart request never fails because of it.
+The job and the subscribers let a read failure propagate (the job runs again,
+the event is retried).
+
+#### Feature toggle
+
+The switch lives under the plugin key `free_shipping`; Storefronts read it
+from `GET /store/plugin-features/free_shipping`.
+
+| Key             | Label             | Default | Gates                                                                                                                             | Keeps running while off                                                                                                         |
+| --------------- | ----------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| (plugin switch) | Versandkostenfrei | on      | status of the promotions `AUTO-FREE-SHIPPING-STANDARD` and `AUTO-FREE-SHIPPING-AFFILIATE` (active while on, inactive while off) | the settings (thresholds stay editable and are synced into the inactive promotions), the `free-shipping-promotion-sync` job (it deactivates the promotions), the promotion-context hook on the cart path |
+
+There are no sub-features. No route answers 404 because of the switch; the
+store-visible effect of "off" is that the two automatic promotions are
+inactive. The switch takes effect immediately on an Admin change and at the
+latest with the next 15-minute job run otherwise.
+
+#### Migrations
+
+The module ships the migrations of the former package unchanged: the 0.2.0
+migration dropped the old `free_shipping_settings` table and carried stored
+thresholds and affiliate rules over into `plugin_setting_state` /
+`plugin_feature_state`. A shop that used the former package keeps its data;
+`medusa db:migrate` after upgrading is enough.
+
+### Dateispeicher (S3)
 
 The base provides a Medusa File Module provider for durable S3-compatible
 asset storage with a local, TTL-based read cache (`providers/s3-cache`), and
 the `/files` gateway routes every provider URL points at. It supports AWS S3,
-MinIO and compatible endpoints through AWS SDK v3. There is no separate S3
-package since 1.0.0; the provider identifier `s3-cache` and the resolve path
-`@hartl-services/medusa-base/providers/s3-cache` replace the old one.
+MinIO and compatible endpoints through AWS SDK v3. The provider identifier is
+`s3-cache` and its resolve path `@hartl-services/medusa-base/providers/s3-cache`
+(part of the base since 1.0.0, see "Upgrading").
 
 S3 is always the source of truth. The local cache is a per-replica performance
 optimization and may be discarded at any time without data loss.
 
-### Coverage
+#### Coverage
 
 The provider covers every asset that uses Medusa's native `Modules.FILE`
 service:
@@ -3427,7 +3511,7 @@ It cannot transparently back up a plugin that writes directly to its own local
 directory, own S3 client, or a third-party URL. Such integrations must be
 changed to use `Modules.FILE` or migrated explicitly.
 
-### Configuration
+#### Configuration
 
 ```ts
 // medusa-config.ts
@@ -3503,7 +3587,7 @@ options) is optional; see
 [Active S3 options and defaults](#active-s3-options-and-defaults) below. The
 provider has no database migrations to run.
 
-### Environment helpers
+#### Environment helpers
 
 `@hartl-services/medusa-base/config` also exports small helpers for reading
 the deployment variables in `medusa-config.ts`:
@@ -3519,7 +3603,7 @@ the deployment variables in `medusa-config.ts`:
 - `resolveExpirationStrategy(process.env, defaultValue)` — reads
   `S3_CACHE_STORAGE_EXPIRATION_STRATEGY` (`"absolute"` or `"sliding"`).
 
-### Runtime configuration
+#### Runtime configuration
 
 The demo shop (`apps/backend`) enables S3 Cache Storage as the sole Medusa
 File Module provider through the preset; there is no per-deployment feature
@@ -3539,7 +3623,7 @@ S3 keys unless the matching database and storage rollback is being performed.
 The local provider cannot read S3-backed IDs. Treat a storage-provider change
 as a controlled deployment cutover, not as a runtime storage router.
 
-#### Active S3 options and defaults
+##### Active S3 options and defaults
 
 In this demo host, `bucket`, `region`, and the File Gateway base URL are
 required.
@@ -3561,7 +3645,7 @@ URLs may use only HTTP(S), with no credentials, query string, or fragment.
 Prefixes and provider keys reject absolute paths, traversal, control
 characters, and backslashes.
 
-### Object and access model
+#### Object and access model
 
 New uploads have opaque keys. The original filename is stored only as encoded
 object metadata:
@@ -3596,7 +3680,7 @@ successful remote write/delete evicts the affected entry only after S3 has
 accepted it. Do not share the cache directory between replicas; use a bounded
 `emptyDir` or per-pod volume and monitor free disk space.
 
-### Backup and restore
+#### Backup and restore
 
 A complete restore requires both a PostgreSQL backup and the versioned object
 store. The cache is not a backup and is intentionally excluded.
@@ -3619,7 +3703,7 @@ count and total bytes without modifying data:
 medusa exec ./node_modules/@hartl-services/medusa-base/.medusa/server/src/documents/scripts/verify-documents-file-storage.js
 ```
 
-### HTTP contract
+#### HTTP contract
 
 The gateway routes expose `GET /files/:asset` for public immutable files and
 `GET /files/private/:token` for signed private capability URLs. Both call
@@ -3630,126 +3714,234 @@ Paths, query types, and the runtime query schema are exported from the separate
 normally consume the complete URL returned by Medusa and never construct a
 private URL themselves.
 
-## Shop-Config-Preset
+## Shop behaviour and operations
 
-`@hartl-services/medusa-base/shop-config` turns a food shop's configuration
-from about 290 lines into about 30: the plugin list and order, the Redis event
-bus, SMTP notifications, S3 file storage, the tax and Stripe payment providers,
-the Admin path, the Sentry logger bridge and the environment validation are
-assembled there; the shop supplies only its own facts. It reuses the `/config`
-helpers above for environment parsing. It is a separate subpath because it
-loads the Sentry logger wrapper and with it `@sentry/node`; `/config` stays
-free of it.
+Behaviour the base adds to every shop without a toggle, and the
+`medusa-config.ts` helpers for operating it.
 
-The preset registers the base (with its E-Mail, Documents and `/files`
-options, and its Tax provider) plus four feature plugins, in this order:
-`medusa-base`, `medusa-free-shipping`, `medusa-batch-management`,
-`medusa-affiliate`, `medusa-payload-sync`.
+### Root redirect
 
-### Installation in a shop
+Medusa serves nothing at `/`, so a deployed domain answers it with a 404. The
+base registers `GET /` and answers with a `302` to the shop's `admin.path`
+(read from the config module, fallback `/app`), so opening the bare domain
+lands on the admin dashboard in every shop and in local development without a
+reverse-proxy rule. The redirect is temporary on purpose: browsers cache a
+`301` on the bare domain essentially forever, which would be painful to undo
+should `/` ever get real content. A shop that needs its own `/` defines
+`src/api/route.ts` itself.
 
-```bash
-pnpm add @hartl-services/medusa-base \
-  @hartl-services/medusa-free-shipping \
-  @hartl-services/medusa-batch-management \
-  @hartl-services/medusa-affiliate \
-  @hartl-services/medusa-payload-sync \
-  @medusajs/event-bus-redis @medusajs/payment-stripe \
-  @sentry/node
-```
+### Cart-promotion link repair
 
-### Usage
+Medusa's `deletePromotionsWorkflow` only soft-deletes a promotion and leaves
+its `cart_promotion` link rows behind, so every cart that had it applied
+reads back a `null` entry inside `cart.promotions`. The base removes those
+links itself:
+
+- The `deletePromotionsWorkflow.hooks.promotionsDeleted` hook
+  (`workflows/hooks/dismiss-deleted-promotion-cart-links`) dismisses the
+  links of the deleted promotions and restores them if a later step fails.
+- The migration script `dismiss-orphaned-cart-promotion-links` runs once in
+  `medusa db:migrate` and removes the links that already dangle from earlier
+  deletions. Medusa tracks migration scripts by file name in
+  `script_migrations`, so the name must not change.
+
+Nothing to configure; `medusa db:migrate` after installing or upgrading to
+0.4.1 is enough.
+
+### Draft orders and 0 € orders
+
+Draft orders (Medusa's `@medusajs/draft-order` plugin, loaded by default) are
+the shop's way to enter an order in the Admin: sample shipments, orders taken
+by phone, replacements. Item prices and the shipping amount are set directly
+in the draft; converting it never involves a payment provider.
+
+- **Customer order confirmation off by default.** The
+  `createOrderWorkflow.hooks.orderCreated` hook
+  (`workflows/hooks/draft-order-confirmation-default`) sets Medusa's
+  `no_notification` on every new draft, also when an API caller sent
+  `no_notification_order: false`. The Admin switches it per draft in the
+  **Bestellbestätigung** widget on the draft's detail page
+  (`GET`/`POST /admin/draft-orders/:id/order-confirmation`, see the E-Mail
+  "Admin API"). On conversion the `order-placed` subscriber records the
+  customer confirmation as `suppressed` (`notifications_disabled`); the copy
+  to the shop's order address is still sent. The shipment mail follows the
+  Admin's "notify customer" choice per shipment, not this switch.
+- **0 € orders count as paid.** Medusa derives an order's payment status from
+  its payment collections only, so a converted 0 € draft would stay
+  "Nicht bezahlt". The subscriber `order-zero-total-paid` runs
+  `order-mark-zero-total-paid` on `order.placed`: an order with a total of 0
+  and no payment collection gets a completed 0 € payment collection and reads
+  "Bezahlt" (`payment_status: captured`). Orders that already carry a
+  collection, i.e. every checkout order, are left alone. In SQL, a paid
+  order is one whose linked `payment_collection` (via
+  `order_payment_collection`) has `status = 'completed'`.
+
+Orders placed before installing this version keep their state.
+
+### Password policy
+
+Medusa's `emailpass` provider accepts any non-empty password. The base runs a
+middleware on `POST /auth/:actor_type/emailpass/register` (customer sign-up,
+Admin invite) and `POST /auth/:actor_type/emailpass/update` (password reset).
+It is registered on `/auth/:actor_type/:auth_provider/:action` without
+`methods` and decides on the decoded, lowercased params, because Express
+matches literal path segments against the raw path: `/auth/customer/email%70ass/register`
+and `/auth/Customer/emailpass/register` reach Medusa's handler too, and
+`Customer` counts as the customer actor here.
+A password that breaks the rules of the actor is answered with
+`400 { type: "invalid_data", message }`; the one German message lists every
+unmet rule, e.g. `Das Passwort erfüllt nicht alle Regeln: mindestens 12
+Zeichen, eine Ziffer.` The check runs before Medusa's reset-token check, so a
+rejected password leaves the single-use reset link valid for a second attempt.
+
+**Admin users** (every actor type except `customer`) always need at least 15
+characters, counted as Unicode code points, and no composition rules. This
+follows NIST SP 800-63B Rev. 4 (the US guideline for digital identity) for a
+password that is the only factor.
+
+**Customers** follow the settings of the "Kunden-Login" plugin (group
+"Passwort-Regeln", Settings > "Hartl Services Plugins"). They apply only while
+`email_password` is on and take effect at once, without a cache:
+
+| Key                           | Label                                | Default | Meaning |
+| ----------------------------- | ------------------------------------ | ------- | ------- |
+| `password_min_length`         | Mindestlänge                         | 15      | 8 to 128 characters, whole numbers only (`integer`); NIST SP 800-63B Rev. 4 recommends at least 15 when the password is the only factor |
+| `password_require_mixed_case` | Groß- und Kleinbuchstaben verlangen  | off     | at least one uppercase and one lowercase letter |
+| `password_require_digit`      | Ziffer verlangen                     | off     | at least one digit |
+| `password_require_symbol`     | Sonderzeichen verlangen              | off     | at least one punctuation mark or symbol (Unicode category P or S; whitespace, combining marks and invisible characters do not count) |
+
+NIST SP 800-63B Rev. 4 advises against composition rules, because they lead to
+predictable passwords such as "Passwort1!"; a longer password protects better.
+The Admin texts say so. A missing or invalid stored value falls back to the
+default of that rule, and if the settings cannot be read at all the default
+policy (15 characters, no composition rules) applies and a warning is logged,
+so a registration is never blocked by a settings outage.
+
+**Route.** `GET /store/customer-auth/password-policy` (publishable key only)
+answers `{ password_policy: { min_length, require_mixed_case, require_digit,
+require_symbol } }`, the effective customer rules, and 404 while
+`email_password` is off. The storefront shows them in its forms and checks
+them with the same functions as the backend. The types, the path
+(`customerAuthStorePaths.get.passwordPolicy`) and the rules
+(`evaluatePasswordPolicy`, `isPasswordAllowed`, `DEFAULT_CUSTOMER_PASSWORD_POLICY`,
+`ADMIN_PASSWORD_POLICY` in `schemas/password-policy`) come from the Contracts
+package.
+
+**Admin passwords and the shared identity.** An `emailpass` identity is shared
+by all actor types: someone invited as an Admin could register through
+`/auth/customer/emailpass/register` with the (weaker) customer rules, log in at
+`/auth/user/emailpass` and accept the invite with that token, which would bind
+the weak password to an Admin. So the Admin login (`POST` and `GET`
+`/auth/user/emailpass`, decoded and lowercased like above) checks the body
+password against the Admin rules and answers the same `400` when the identity
+has no Admin yet (`app_metadata.user_id` unset). The login of an identity that
+already belongs to an Admin is never checked. Remaining limit, deliberately not
+closed: a customer could register through the Admin path with 15 characters and
+no composition rules although the shop asks for more; that only weakens their
+own password.
+
+Login of a customer is not checked, so existing passwords keep working until their next
+reset, whatever the rules are. Accounts created without HTTP (`medusa user`,
+seed scripts calling the Auth module) are not checked either.
+
+### Config helpers
+
+`@hartl-services/medusa-base/config` holds the generic environment helpers a
+shop's `medusa-config.ts` needs, so every shop fails at startup with the name
+of the missing variable instead of a runtime crash. The environment helpers
+have no dependency on Medusa; the subpath does not load `@sentry/node`.
+
+| Export | Purpose |
+|---|---|
+| `ConfigurationPhase` | `"build" \| "runtime"` |
+| `MEDUSA_BUILD_PLACEHOLDERS` | Placeholders for `ADMIN_CORS`, `AUTH_CORS`, `COOKIE_SECRET`, `DATABASE_URL`, `JWT_SECRET`, `MEDUSA_BACKEND_URL`, `STOREFRONT_URL`, `STORE_CORS`, `STRIPE_API_KEY`, `STRIPE_WEBHOOK_SECRET` |
+| `requireEnvironment(environment, names, phase, buildPlaceholders)` | Returns every named value (trimmed) or throws one error listing all missing names; in the build phase `buildPlaceholders` fill in for deployment values |
+| `optionalEnvironment`, `integerEnvironment`, `booleanEnvironment` | Trimmed optional string, range-checked integer, strict `"true"`/`"false"` boolean |
+| `allowsInsecureLocalServices(environment, phase)` | `true` for build, development and test |
+| `resolvePublicOrigin(value, name, allowHttp)`, `shopUrl(origin, path)` | Validate a bare HTTP(S) origin; build an absolute URL that cannot leave the origin |
+| `resolveStripe(values)` | Checks the `sk_` key and the `whsec_` webhook secret |
+| `resolveRedisEventBus(environment, phase)` | `{ url } \| undefined`: optional in development, required at runtime elsewhere, never used in a build, authenticated `rediss://` in production |
+| `createEmailNotificationModuleConfig`, `defineShopEmailConfiguration` (deprecated: `createSmtpNotificationModuleConfig`, `resolveSmtp`, `SMTP_ENVIRONMENT_VARIABLES`, `SMTP_BUILD_PLACEHOLDERS`) | Mail notification provider and E-Mail configuration (see "E-Mail") |
+| `createS3CacheStorageConfig`, `createS3CacheFileModuleConfig`, `resolveS3Credentials`, `resolveExpirationStrategy`, `S3_BUILD_PLACEHOLDERS` | S3 file storage (see "Dateispeicher (S3)") |
+| `createDefaultDocumentHtmlFactory`, `DOCUMENTS_BUILD_PLACEHOLDERS` | Documents markup and build placeholder (see "Dokumente") |
+
+`medusa build` loads the configuration without deployment secrets. Each
+plugin's own placeholders (SMTP, S3, PDF executable, ...) live with that
+plugin; the shop merges them:
 
 ```ts
 // medusa-config.ts
-import { defineFoodShopConfig } from "@hartl-services/medusa-base/shop-config"
+import {
+  MEDUSA_BUILD_PLACEHOLDERS,
+  requireEnvironment,
+  resolveRedisEventBus,
+  type ConfigurationPhase,
+} from "@hartl-services/medusa-base/config"
 
-module.exports = defineFoodShopConfig({
-  displayName: "EXAMPLE SHOP",
-  orderNotificationEmail: "orders@example.com",
-  timeZone: "Europe/Vienna",
-  storefrontCountryCode: "de",
-})
+const phase: ConfigurationPhase =
+  process.env.MEDUSA_BUILD_PHASE === "true" ? "build" : "runtime"
+const env = requireEnvironment(
+  process.env,
+  ["DATABASE_URL", "JWT_SECRET", "COOKIE_SECRET"],
+  phase,
+  { ...MEDUSA_BUILD_PLACEHOLDERS /* , ...other plugins' placeholders */ },
+)
+const redis = resolveRedisEventBus(process.env, phase)
 ```
 
-A shop that has to adjust the result (a test harness, for example) builds the
-plain input, changes it and calls `defineConfig` itself:
+### Sentry logger wrapper
+
+`@hartl-services/medusa-base/sentry-logger` exports `withSentryErrorReporting(logger)`,
+formerly published as `@hartl-services/medusa-sentry-logger`. Medusa's HTTP
+error handler catches thrown route and workflow errors and only logs them, so
+Sentry's default Node integrations never see them; wrapping the logger reports
+every `logger.error(...)` and every `Error` passed to `logger.warn(...)` (at
+level `warning`). It is a plain library import for `medusa-config.ts`, not a
+Medusa plugin feature, and needs `@sentry/node` (an optional peer dependency):
 
 ```ts
-import { defineConfig } from "@medusajs/framework/utils"
-import { buildFoodShopConfig } from "@hartl-services/medusa-base/shop-config"
+import { logger } from "@medusajs/framework/logger";
+import { withSentryErrorReporting } from "@hartl-services/medusa-base/sentry-logger";
 
-const config = buildFoodShopConfig(options)
-config.plugins = config.plugins.filter(
-  (plugin) => plugin.resolve !== "@hartl-services/medusa-batch-management",
-)
-module.exports = defineConfig(config)
+module.exports = defineConfig({
+  logger: withSentryErrorReporting(logger),
+  // ...
+});
 ```
 
-### API
-
-- `defineFoodShopConfig(options, environment = process.env)` returns
-  `defineConfig(buildFoodShopConfig(options, environment))`.
-- `buildFoodShopConfig(options, environment = process.env)` returns the plain
-  config input (`admin`, `logger`, `projectConfig`, `modules`, `plugins`)
-  before `defineConfig`. `modules` and `plugins` are ordinary arrays.
-- Types: `FoodShopConfigOptions`, `FoodShopConfigInput`, `FoodShopPlugin`,
-  `FoodShopModule`.
+Initialize Sentry in `instrumentation.ts` as usual; without a `SENTRY_DSN` the
+wrapper is inert.
 
-Both functions validate the options first and throw a `TypeError` naming the
-option (`Food shop option "timeZone" must be ...`), so a misconfigured shop
-fails at boot. They then load the `.env` file (unless disabled) and read and
-validate the environment; a missing variable fails with the variable's name.
+### Sentry instrumentation
 
-### Options
+`@hartl-services/medusa-base/instrumentation` exports `register()`, the hook
+Medusa's start command calls from the shop's `instrumentation.ts`. It runs
+`Sentry.init` with `SENTRY_DSN`, `SENTRY_ENVIRONMENT` (fallback `NODE_ENV`)
+and `tracesSampleRate: 0`; without a `SENTRY_DSN` Sentry stays inert. The
+shop's `instrumentation.ts` is one line:
 
-| Option | Meaning |
-| --- | --- |
-| `displayName` | Shop name in the default e-mail templates (a shop's initial seed may use it as store name). Company name, address and UID are no options: documents and tax compliance read them only from the Shop-Stammdaten (Admin, "Hartl Services Plugins"). |
-| `orderNotificationEmail` | Receives order notification e-mails; must look like an e-mail address. |
-| `timeZone` | IANA time zone (validated with `Intl`). Chooses the annual document-number period, the printed dates on documents and the affiliate consignment reminder time zone. |
-| `storefrontCountryCode` | 2-letter lowercase country code of the storefront route. Links: `<STOREFRONT_URL>/<cc>/partnerportal` (affiliate portal), `<STOREFRONT_URL>/<cc>/reset-password` and `<STOREFRONT_URL>/<cc>/verify-account` (the e-mail plugin appends `#token=`), referral base `<STOREFRONT_URL>/<cc>`. The Admin invite link is `<MEDUSA_BACKEND_URL>/app/invite?token=`. |
-| `documentHtmlFactory` | Optional `DocumentHtmlFactory` that replaces the default document markup, typically `createDefaultDocumentHtmlFactory({ timeZone, theme })` from `/config` with the shop's CSS and watermark (see "Layout, logo, payment terms and shop theme"). Must be a function. |
-| `loadEnvFile` | Default `true`: calls `loadEnv(NODE_ENV \|\| "development", process.cwd())`. Pass `false` when the environment is already complete (tests, isolated child processes). |
+```ts
+export { register } from "@hartl-services/medusa-base/instrumentation"
+```
 
-### Environment variables
+`@sentry/node` stays an optional peer dependency of the base: a shop that uses
+this export (or `sentry-logger`) lists `@sentry/node` in its own
+`dependencies`.
 
-Required at runtime (during `medusa build`, with `MEDUSA_BUILD_PHASE=true`, the
-plugins' build placeholders stand in for them):
+## Development
 
-- Medusa core: `DATABASE_URL`, `STORE_CORS`, `ADMIN_CORS`, `AUTH_CORS`,
-  `JWT_SECRET`, `COOKIE_SECRET`, `MEDUSA_BACKEND_URL`, `STOREFRONT_URL` (plain
-  HTTP origins are accepted only in development and test).
-- Redis: `REDIS_URL` (optional in development, where Medusa's local event bus
-  is used; required elsewhere, `rediss://` with authentication in production
-  unless `REDIS_ALLOW_INSECURE_PRIVATE_NETWORK=true`). Never used during a
-  build.
-- SMTP: `SMTP_HOST`, `SMTP_PORT`, `SMTP_SECURE`, `SMTP_USER`, `SMTP_PASSWORD`,
-  `SMTP_FROM`, `SMTP_REQUIRE_TLS` (outside development and test either
-  `SMTP_SECURE` or `SMTP_REQUIRE_TLS` must be `true`).
-- Stripe: `STRIPE_API_KEY` (`sk_...`), `STRIPE_WEBHOOK_SECRET` (`whsec_...`).
-- S3: `S3_CACHE_STORAGE_BUCKET`, `S3_CACHE_STORAGE_REGION`.
-- Documents: `DOCUMENT_PDF_EXECUTABLE`.
+### Local e-mail development
 
-Optional: `S3_CACHE_STORAGE_ENDPOINT`, `S3_CACHE_STORAGE_FORCE_PATH_STYLE`,
-`S3_CACHE_STORAGE_PREFIX`, `S3_CACHE_STORAGE_ACCESS_KEY_ID`,
-`S3_CACHE_STORAGE_SECRET_ACCESS_KEY`, `S3_CACHE_STORAGE_SESSION_TOKEN` (omit
-the keys to use the AWS credential chain), `S3_CACHE_STORAGE_CACHE_DIR`
-(default `./.medusa-s3-cache`), `S3_CACHE_STORAGE_TTL_MS`,
-`S3_CACHE_STORAGE_CLEANUP_INTERVAL_MS`,
-`S3_CACHE_STORAGE_EXPIRATION_STRATEGY`,
-`FILE_GATEWAY_PRIVATE_DOWNLOAD_DURATION_SECONDS`, and `SENTRY_DSN` /
-`SENTRY_ENVIRONMENT` for error tracking (see the base's
-`/instrumentation`).
+For local development, provide the seven SMTP variables and omit `REDIS_URL` to
+use Medusa's local Event Bus. Set `REDIS_URL` only when intentionally exercising
+the direct Redis provider. The backend HTTP runner ignores ambient Redis and
+SMTP settings and injects an isolated Redis container, unique queue, and
+token-protected SMTP fixture for every child.
 
-### Fixed configuration
+### Build output of `/admin-components`
 
-Not configurable on purpose: the plugin order (base first), the Redis event
-bus job policy (3 attempts, exponential backoff from 1 s), S3 cache defaults
-(15 min cleanup, 1 h TTL, absolute expiration), Stripe immediate capture with
-automatic payment methods, the 24 h session lifetime, Admin path `/app`,
-consignment reminders due on day 10, the Documents module always being part of the base, and
-`http.authVerificationsPerActor.customer` (a getter that follows the E-Mail `customer_verification` toggle, see
-"Kontobestätigung per E-Mail"), `http.authMethodsPerActor` (customers: a getter that follows the `customer_auth` switches; Admin users: `["emailpass"]`) and the auth module entry
-(providers `emailpass` and `email-otp`, the latter with `hmacSecret` = `JWT_SECRET`, the same value as `http.jwtSecret`; see
-"Kunden-Login").
+`/admin-components` is built (after `medusa plugin:build`) into
+`.medusa/server/src/admin/admin-components`, not into `dist`: the host Admin's
+Tailwind scans only `.medusa/server/src/admin/**` of a plugin, so the classes of
+the shared components are generated there. Do not move the outDir of
+`tsconfig.admin-components.json`.