Refresh v4.8.x docs and fix CI, Docker, runtime, and MCP validation

.dockerignore

@@ -1,14 +1,25 @@
 .git
+.context
+.claude
+.agents
 .github
 .db
-.next
-.env
 .tmp
 .build
-.claude
-docs
-node_modules
 typedocs
-examples/*/lib
-examples/*/.db
+docs
+**/node_modules
+**/.next
+**/.docusaurus
+**/.db
+**/coverage
+**/out
+env
+**/.env*
+!.env.tests
+!**/.env.defaults
+!admin-ui/.env
+!admin-ui/.env.development
 packages/*/lib
+examples/*/lib
+**/*.tsbuildinfo

.forgejo/MIGRATION.md

@@ -19,7 +19,7 @@ and add a **Trivy** vulnerability gate.
 | Runs on | `jenkins.ucc.dev` | `git.ucc.dev` runner (`runs-on: docker`) |
 | docs image | `registry.ucc.dev/unchained/docs` | `git.ucc.dev/unchained/unchained/docs` |
 | adminui image | `registry.ucc.dev/unchained/adminui` | `git.ucc.dev/unchained/unchained/adminui` |
-| Lint / tests | ci image: `npm run lint` (gate) + `npm run test \|\| :` (non-blocking) | same, faithfully ported |
+| Lint / tests | CI image: nonmutating `npm run lint:check` and blocking `npm test` | Same gates; docs publishing requires both plus Trivy |
 | Vuln scan | none | Trivy `fs` gate (fixable HIGH/CRITICAL) |
 
 Tagging is preserved: docs → `<branch>-latest`, `next`@develop, `latest`@master,
@@ -28,8 +28,8 @@ Tagging is preserved: docs → `<branch>-latest`, `next`@develop, `latest`@maste
 @tag. The adminui **major tags are consumed in prod** (`adminui:1`,`:v2`,`:v3`) —
 they must keep publishing.
 
-> **The `@unchainedshop/*` npm packages are out of scope** — they aren't built by
-> Jenkins and aren't built here.
+> **The `@unchainedshop/*` npm packages are out of scope** — npm publishing is not handled by
+> Jenkins or these workflows. CI compiles the packages and runs their tests.
 
 ---
 
@@ -64,16 +64,16 @@ label `docker`) picks the jobs up automatically.
 
 | Kind | Name | Value |
 |---|---|---|
-| Secret | `REGISTRY_TOKEN` | a **`write:package`** PAT for the `unchained` org (the automatic Actions token cannot push packages). |
+| Secret | `PKG_PUSH_TOKEN` | a **`write:package`** PAT for the `unchained` org (the automatic Actions token cannot push packages). |
 | Secret | `TESTS_DOTENV` | the dotenv used by the integration tests (was the Jenkins `unchained-dotenv` credential; written to `./env` before the CI image build). |
 
 (Optional) set variable `REGISTRY_USER` to override the login user.
 
 ### 5. Verify
 
-- Open a PR → **`test`** (lint gates; tests non-blocking) and **`trivy`** run.
+- Open a PR → **`test`** (nonmutating lint, unit, integration, and Docker healthcheck regression tests all gate) and **`trivy`** run.
 - Push `develop`/`master`/a version branch → **`docs`** publishes; a change under
-  `admin-ui/**` also triggers **admin-ui**. Confirm images under the repo's
+  `admin-ui/**` or its shared workspace/build inputs also triggers **admin-ui**. Confirm images under the repo's
   **Packages** tab: `git.ucc.dev/unchained/unchained/{docs,adminui}` with the
   expected tags (incl. adminui `vMAJOR`).
 
@@ -123,8 +123,9 @@ comment-triggered runs there; it is untouched.
 
 - `@unchainedshop/*` npm package publishing (not a Jenkins pipeline).
 - `.deepsource.toml` (SaaS static analysis) is unchanged.
-- Tests remain **non-blocking** (`|| :`), exactly as Jenkins ran them; lint is the
-  hard gate. Tighten by dropping `|| :` once the suite is reliably green.
-- BuildKit: Jenkins forced `DOCKER_BUILDKIT=0`; the new pipeline uses buildx for the
-  docs/adminui images. If one fails under buildx, fall back to a plain `docker build`/
-  `docker push` step (the runner has host docker.sock).
+- Lint, tests, and image builds are blocking. Test failures stop the pipeline and
+  prevent dependent image publishing. Lint uses `lint:check` and does not rewrite files.
+- Docker builds use the repository root as their context. Runtime images and `.nvmrc`
+  pin Node.js 26.8.2; package engines require Node.js 26.8.2 or newer.
+- Image publishing uses plain `docker build` and `docker push` through the host
+  `docker.sock`; the workflows avoid buildx because pushes to the Forgejo registry failed.

.forgejo/workflows/admin-ui.yml

@@ -1,8 +1,8 @@
 name: admin-ui
 
 # Forgejo Actions pipeline for the admin-ui image (replaces admin-ui/Jenkinsfile).
-# Scoped by `paths` so it only rebuilds when admin-ui/ changes. The admin-ui
-# Dockerfile runs `npm run lint && npm run build` internally, so building the
+# Scoped to the admin UI and its shared workspace/build inputs. The admin-ui
+# Dockerfile runs `npm run lint:check && npm run build` internally, so building the
 # image is its own lint/build gate; a Trivy scan of admin-ui/ gates the publish.
 # Semver tags mirror the Jenkinsfile and ARE consumed in prod (adminui:1|v2|v3).
 
@@ -12,10 +12,22 @@ on:
     tags: ['*']
     paths:
       - 'admin-ui/**'
+      - 'packages/**'
+      - 'package.json'
+      - 'package-lock.json'
+      - '.nvmrc'
+      - '.dockerignore'
+      - 'docker/**'
       - '.forgejo/workflows/admin-ui.yml'
   pull_request:
     paths:
       - 'admin-ui/**'
+      - 'packages/**'
+      - 'package.json'
+      - 'package-lock.json'
+      - '.nvmrc'
+      - '.dockerignore'
+      - 'docker/**'
       - '.forgejo/workflows/admin-ui.yml'
   workflow_dispatch:
 
@@ -108,7 +120,7 @@ jobs:
           docker build --platform linux/amd64 \
             --label "org.opencontainers.image.source=https://git.ucc.dev/${GITHUB_REPOSITORY}" \
             --build-arg GIT_COMMIT="${GITHUB_SHA}" \
-            $TAG_ARGS -f ./admin-ui/Dockerfile ./admin-ui
+            $TAG_ARGS -f ./admin-ui/Dockerfile .
           for t in $TAGS; do
             echo "==> Pushing ${IMAGE}:${t}"
             docker push "${IMAGE}:${t}"

.forgejo/workflows/ci.yml

@@ -5,7 +5,7 @@ name: CI
 # to the git.ucc.dev package registry, gated by a Trivy scan. The admin-ui image
 # has its own workflow (admin-ui.yml). The @unchainedshop/* npm packages are
 # published separately and are NOT handled here (they weren't in Jenkins either).
-# See MIGRATION.md for repo/secret setup and the GitHub push-mirror (phase 2).
+# See .forgejo/MIGRATION.md for repo/secret setup and the GitHub push-mirror (phase 2).
 
 on:
   push:
@@ -19,10 +19,9 @@ env:
   REGISTRY_REPO: unchained/unchained
 
 jobs:
-  # Faithful port of the Jenkins Test stage: build the mongo-based CI image
-  # (root Dockerfile: mongo:8.2.12 + Node via nvm + MONGOMS_SYSTEM_BINARY, runs
-  # `npm ci` + `npm run build`), then lint (gate) and test (non-blocking, exactly
-  # as Jenkins ran `npm run test || :`). Uses the host docker daemon (docker.sock).
+  # Build the mongo-based CI image with the pinned Node version and workspace
+  # dependencies, then require nonmutating lint and all test suites to pass.
+  # Uses the host docker daemon (docker.sock).
   test:
     name: Lint + tests (mongo-backed)
     runs-on: docker
@@ -38,12 +37,12 @@ jobs:
       - name: Build CI image
         run: docker build -t unchained-ci:${{ github.sha }} .
       - name: Lint
-        run: docker run --rm unchained-ci:${{ github.sha }} npm run lint
-      - name: Tests (non-blocking, as in Jenkins)
-        run: docker run --rm unchained-ci:${{ github.sha }} sh -c "npm run test || :"
+        run: docker run --rm unchained-ci:${{ github.sha }} npm run lint:check
+      - name: Unit, integration, and healthcheck tests
+        run: docker run --rm unchained-ci:${{ github.sha }} npm test
 
   # Source-dependency scan across the whole monorepo (incl. admin-ui).
-  # Hard-gates on fixable HIGH/CRITICAL (ADR-003).
+  # Hard-gates on fixable HIGH/CRITICAL vulnerabilities.
   trivy:
     name: Trivy vuln gate
     runs-on: docker
@@ -116,7 +115,7 @@ jobs:
           docker build --platform linux/amd64 \
             --label "org.opencontainers.image.source=https://git.ucc.dev/${GITHUB_REPOSITORY}" \
             --build-arg GIT_COMMIT="${GITHUB_SHA}" \
-            $TAG_ARGS -f ./docs/Dockerfile ./docs
+            $TAG_ARGS -f ./docs/Dockerfile .
           for t in $TAGS; do
             echo "==> Pushing ${IMAGE}:${t}"
             docker push "${IMAGE}:${t}"

.github/ISSUE_TEMPLATE/bug_report.md

@@ -23,16 +23,15 @@ A clear and concise description of what you expected to happen.
 **Screenshots**
 If applicable, add screenshots to help explain your problem.
 
-**Desktop (please complete the following information):**
- - OS: [e.g. iOS]
- - Browser [e.g. chrome, safari]
- - Version [e.g. 22]
-
-**Smartphone (please complete the following information):**
- - Device: [e.g. iPhone6]
- - OS: [e.g. iOS8.1]
- - Browser [e.g. stock browser, safari]
- - Version [e.g. 22]
+**Environment:**
+
+ - Unchained version or commit:
+ - Affected package, plugin, or example:
+ - Node.js version (`node --version`):
+ - MongoDB version:
+ - Operating system:
+ - Server framework (Fastify/Express), if relevant:
+ - Browser and version, for Admin UI/storefront issues:
 
 **Additional context**
 Add any other context about the problem here.

.nvmrc

@@ -1 +1 @@
-26
+26.8.2

BENCHMARKS.md

@@ -1,3 +1,9 @@
+# Historical Benchmarks
+
+These measurements compare the versions named below. They have not been rerun
+for the current release and do not include a reproducible hardware or workload
+configuration. Treat them as historical observations, not current performance guarantees.
+
 Vendure v3.1.1:
 
 * node_modules size: 262M
@@ -97,4 +103,4 @@ Minimal v2 without optional and without dev (production setup):
 Minimal v3 without optional and without dev (production setup):
 
 - 245 Packages in node_modules
-- 76M
+- 76M

CLAUDE.md

@@ -6,23 +6,25 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ### Development
 ```bash
-npm install          # Install all dependencies (uses npm workspaces)
+npm ci               # Install locked dependencies (uses npm workspaces)
+npm run build:packages # Build package imports before running examples or tests
 npm run dev          # Start development with hot-reload (runs kitchensink example + admin-ui + watches packages)
-npm run build        # Clean all build artifacts and rebuild packages (excludes examples)
+npm run build        # Clean/rebuild TypeScript project references and build the Admin UI
 npm run dev:watch    # Watch mode for TypeScript compilation across all packages
 ```
 
 ### Testing
 ```bash
-npm run test                    # Run all tests (unit + integration)
+npm run test                    # Run unit, integration, and Docker healthcheck regression tests
 npm run test:run:unit       # Run unit tests only (uses node --test in packages/)
-npm run test:run:integration # Run integration tests (uses kitchensink example + tests/)
+npm run test:run:integration # Run tests/ with its own Fastify platform and MongoDB Memory Server
+npm run test:run:docker     # Run healthcheck regression tests without Docker
 node --no-warnings --env-file .env.tests --env-file-if-exists=.env --test-isolation=none --test-force-exit --test-global-setup=tests/helpers.js --test --test-concurrency=1 path/to/test.ts  # Run a single integration test file (run from monorepo root directory)
 node --test path/to/test.ts # Run a single unit test file
 ```
 
 ### Package-Level Commands
-Individual packages support these scripts:
+Most packages support these scripts; check the package's `package.json`:
 ```bash
 cd packages/[package-name]
 npm run build       # Build specific package
@@ -34,7 +36,7 @@ npm run test:watch  # Run tests in watch mode
 ### Code Quality
 ```bash
 npm run lint     # Lint and fix code (ESLint + Prettier)
-npm run pretest  # Run ESLint without fixing
+npm run lint:check # Run ESLint without fixing
 ```
 
 ## Architecture Overview
@@ -80,15 +82,14 @@ Example modules: core-orders, core-products, core-users, core-payment, core-deli
 
 ### Architectural Constraints
 **IMPORTANT**: Respect layer boundaries when working with packages:
-- **DO NOT import `@unchainedshop/mongodb` outside of core-* and infrastructure packages**
-- The API layer (`@unchainedshop/api`) should only use types from core packages, never direct MongoDB imports
-- Database queries and MongoDB-specific logic belong exclusively in core-* modules
-- Higher-level packages (api, platform) should use the module APIs exposed by core packages
+- Keep domain database queries in core-* modules and use their module APIs from higher layers.
+- Infrastructure concerns also use MongoDB directly: API session storage, platform migrations, and plugin-owned collections are existing examples.
+- Prefer type-only imports when a higher layer only needs database types.
 
 ### TypeScript Configuration
 - Uses TypeScript project references (tsconfig.json) for incremental builds
 - All packages build to `lib/` directory with declaration files
-- Run `tsc --build` from root to build all packages respecting dependencies
+- Run `tsc --build` from root to build the packages and examples listed in `tsconfig.json`, respecting dependencies
 - Individual packages have isolated TypeScript configurations
 
 ### API Structure
@@ -107,8 +108,7 @@ The API package supports multiple server frameworks:
 
 ### Environment Configuration
 - Use `.env` files for local configuration
-- Default values in `.env.defaults`
-- Integration tests use `.env.tests` with `.env` as fallback
-- Node.js 22+ required (see .nvmrc)
+- Example-specific defaults are in `examples/*/.env.defaults`; there is no root `.env.defaults`
+- Integration tests load `.env.tests`, then optional root `.env` overrides; existing shell variables take precedence
+- Use Node.js 26.8.2 from `.nvmrc` for development and tests; all package engines require `>=26.8.2`
 - MongoDB required (or use MongoDB Memory Server for testing)
- No newline at end of file

CONTRIBUTING.md

@@ -1,8 +1,56 @@
 # Unchained OSS Contributions
 
-To get started, sign the Contributor License Agreement with your first PR.
+Sign the Contributor License Agreement with your first PR.
 
-1. Branch/Fork
-2. Add your changes, add unit and api tests for your new features
-3. Run all tests locally (npm run test)
-4. Submit a PR
+## Local setup
+
+Fork or clone the repository and create a branch from the release branch you are
+targeting (`v4.8.x` for the current v4 release).
+
+```bash
+nvm install
+nvm use
+npm ci
+npm run build:packages
+npm run dev
+```
+
+Use the Node.js version in `.nvmrc` for the development and test commands. The
+development command starts the kitchensink example, the Admin UI, and the package
+compiler in watch mode. The examples use MongoDB Memory Server when `MONGO_URL`
+is unset; its first run downloads a MongoDB binary.
+
+## Checks before submitting
+
+Add unit and API integration tests for behavior changes, then run:
+
+```bash
+npm run lint:check           # Check without changing files
+npm run build:packages
+npm test                     # Unit, integration, and Docker healthcheck regression tests
+```
+
+`npm run lint` also applies fixes. For Admin UI changes, run
+`npm run lint:check --workspace admin-ui` and `npm run build --workspace admin-ui`.
+
+Integration tests start their own platform through `tests/setup.js`. They load
+`.env.tests` and optional root `.env` overrides; existing shell variables take
+precedence. Run one integration test from the repository root with:
+
+```bash
+node --no-warnings --env-file .env.tests --env-file-if-exists=.env --test-isolation=none --test-force-exit --test-global-setup=tests/helpers.js --test --test-concurrency=1 tests/auth-user.test.js
+```
+
+For a single unit test, use `node --test path/to/test.ts`.
+Scheduler timing benchmarks are opt-in because their fixed millisecond budgets
+depend on hardware and machine load. Scheduler correctness tests always run.
+To run the timing benchmarks on an idle machine:
+
+```bash
+UNCHAINED_SCHEDULE_BENCHMARK=1 node --test --test-name-pattern='schedule performance benchmarks' packages/core/src/utils/schedule.test.ts
+```
+
+See [docs/README.md](docs/README.md) for documentation development and validation.
+
+Submit a PR against the target release branch with a description of the change
+and the checks you ran. Report vulnerabilities through [SECURITY.md](SECURITY.md).