@multisystemsuite/create-mf-app 1.0.5 → 1.0.8

package/README.md

@@ -1,204 +1,817 @@
 # create-mf-app
 
-TypeScript CLI that scaffolds enterprise microfrontend applications and monorepos using React 19, Vite 7, Module Federation, React Router, Docker, and npm workspaces.
+**`@multisystemsuite/create-mf-app`** — TypeScript CLI that scaffolds production-grade **enterprise microfrontend platforms** using React 19, Vite 7, Module Federation, React Router, Material UI, Docker, and npm workspaces.
+
+Inspired by **Nx**, **Turborepo**, **Backstage**, and **Module Federation** — optimized for React microfrontends, Vite, runtime federation, SaaS dashboards, and internal developer platforms.
+
+---
+
+## Table of contents
+
+- [Install & run the CLI](#install--run-the-cli)
+- [What it generates](#what-it-generates)
+- [Quick start](#quick-start)
+- [How to use the generated project](#how-to-use-the-generated-project)
+- [CLI reference (create-mf-app)](#cli-reference-create-mf-app)
+- [Custom child & shared app names](#custom-child--shared-app-names)
+- [Enterprise platform flags](#enterprise-platform-flags)
+- [Generated monorepo structure](#generated-monorepo-structure)
+- [MF Platform CLI (inside generated projects)](#mf-platform-cli-inside-generated-projects)
+- [Using corelib (shared library)](#using-corelib-shared-library)
+- [Enterprise design system & theming](#enterprise-design-system--theming)
+- [Module Federation](#module-federation)
+- [SDK packages](#sdk-packages)
+- [Task runner & build cache](#task-runner--build-cache)
+- [Plugins & devtools](#plugins--devtools)
+- [Runtime configuration](#runtime-configuration)
+- [Template marketplace](#template-marketplace)
+- [CI/CD & governance](#cicd--governance)
+- [Code quality](#code-quality)
+- [Root workspace scripts](#root-workspace-scripts)
+- [Docker & deployment](#docker--deployment)
+- [Documentation in generated projects](#documentation-in-generated-projects)
+- [Node version](#node-version)
+- [Troubleshooting](#troubleshooting)
+- [Develop & publish this package](#develop--publish-this-package)
+
+---
+
+## Install & run the CLI
+
+You do **not** need to clone this repo to use the tool. Install and run via **npx** (recommended):
+
+```bash
+npx @multisystemsuite/create-mf-app@latest my-platform --type=parent --children=billing,orders --shared=corelib --template=tsx
+```
+
+Or use the short binary name (same package):
+
+```bash
+npx create-mf-app my-platform --type=parent --children=billing,orders --shared=corelib
+```
+
+**Global install** (optional):
+
+```bash
+npm install -g @multisystemsuite/create-mf-app
+create-mf-app my-platform --type=parent --children=billing,orders --shared=corelib
+```
+
+**Interactive mode** (no project name — prompts for all options):
+
+```bash
+npx create-mf-app
+```
+
+**Help:**
+
+```bash
+npx create-mf-app --help
+```
+
+After scaffolding, always:
+
+```bash
+cd <project-name>
+npm install
+```
+
+Then use the scripts in [How to use the generated project](#how-to-use-the-generated-project).
+
+---
 
 ## What it generates
 
-- Single app scaffold (`child` mode)
-- Parent monorepo scaffold (`parent` mode) with:
-  - `apps/main` host
-  - multiple remote apps
-  - shared app(s) such as `sharedlib`
-  - root scripts for dev/build/watch/preview/release
+### Single app (`--type=child`)
+
+- React + Vite + Module Federation remote
+- TypeScript (`.tsx`) or JavaScript (`.jsx`)
+- Optional Docker
+- Standalone dev on `--port` (default `3001`)
+
+### Parent monorepo (`--type=parent`)
+
+- **`apps/main`** — host shell (router, sidebar, navbar, command palette)
+- **`apps/<child>`** — federated remotes (names you pass in `--children`)
+- **`apps/corelib`** (or custom `--shared` name) — shared federated library (design system, RBAC, UI)
+- **`packages/*`** — shared npm workspace libraries
+- **`tools/mf-cli`** — Nx-like platform CLI (`mf generate`, `mf graph`, `mf affected`, …)
+- **`task-runner/`** — parallel builds + hash cache (`.mf/cache`)
+- **`plugins/`** — React, Vite, Federation, MUI, Auth, Charts, Workflow, Monitoring
+- **`devtools/`** — federation inspector, profiler, theme inspector
+- **`runtime-config/`** — tenant configs, remote manifests, feature flags
+- **`templates/`** — LIMS, ERP, HMS, SaaS enterprise blueprints
+- **`ai/`** — AI-ready prompt engine + semantic search hooks
+- **`governance/`** — import boundaries, CODEOWNERS, dependency rules
+- **CI/CD** — GitHub Actions, GitLab CI, Helm chart
+- Root scripts for dev, watch, preview, release, affected builds, **per-child dev shortcuts**
+
+---
 
 ## Quick start
 
-Single app:
+### Single remote app
 
 ```bash
-npx create-mf-app inventory --template=tsx --port=3001
+npx create-mf-app inventory --template=tsx --port=3001 --type=child
 cd inventory
 npm install
 npm run dev
 ```
 
-Parent monorepo:
+Open **http://localhost:3001**
+
+### Parent monorepo (full platform)
 
 ```bash
-npx create-mf-app my-platform --type=parent --children=billing,orders,analytics,warehouse --shared=corelib --template=tsx
+npx create-mf-app my-platform \
+  --type=parent \
+  --children=billing,orders,analytics,warehouse \
+  --shared=corelib \
+  --template=tsx
+
 cd my-platform
 npm install
 npm run local
 ```
 
-## CLI usage
+Open **http://localhost:3000** (host). Child remotes load on routes like `/billing`, `/orders`, etc.
+
+### Full enterprise platform (all optional modules)
+
+```bash
+npx create-mf-app my-platform \
+  --type=parent \
+  --children=billing,orders,analytics,warehouse \
+  --shared=corelib \
+  --template=tsx \
+  --auth \
+  --charts \
+  --storybook \
+  --monitoring \
+  --table \
+  --form-engine \
+  --i18n \
+  --testing \
+  --pwa \
+  --plugin-system
+```
+
+---
+
+## How to use the generated project
+
+### First-time setup
+
+```bash
+cd my-platform
+npm install          # hoisted workspaces — required for federation shared deps
+npm run local        # build all apps → watch → preview all ports → live-reload
+```
+
+| Command | When to use |
+|---------|-------------|
+| `npm run local` | **Default daily dev** — all apps (main + every child + shared lib) |
+| `npm run dev` | Print env + run each app's Vite dev server (no federation build watch) |
+| `npm run dev:fast` | Dev build once, then preview + live-reload |
+| `npm run dev:safe` | Production build, then preview only |
+
+### Work on one module only (faster)
+
+The generator creates **one npm script per child name** from `--children`. Each script starts only the apps that module needs:
+
+| You run | Apps started | Typical URL |
+|---------|--------------|-------------|
+| `npm run billing` | main + corelib + billing | http://localhost:3000/billing |
+| `npm run orders` | main + corelib + orders | http://localhost:3000/orders |
+| `npm run analytics` | main + corelib + analytics | http://localhost:3000/analytics |
+| `npm run corelib` | main + corelib | http://localhost:3000 |
+
+**Example:** only billing team local dev:
+
+```bash
+npm run billing
+# edit apps/billing/src/...
+# host reloads billing remote from localhost:3001
+```
+
+Scripts are **generated dynamically** from your `--children` list — if you scaffold with `--children=invoicing,shipping`, you get `npm run invoicing` and `npm run shipping` automatically.
+
+### Port assignment
+
+Ports are assigned sequentially from **3000**:
+
+| App order | Example names | Port |
+|-----------|---------------|------|
+| 1st | `main` (always host) | 3000 |
+| 2nd | first child | 3001 |
+| 3rd | second child | 3002 |
+| … | … | … |
+| last | shared lib (`corelib`) | highest port |
+
+Check your generated root `README.md` or `.env` for the exact map.
+
+### Build for environments
+
+```bash
+npm run build:local      # localdev mode — used by npm run local
+npm run build:dev        # dev
+npm run build:staging    # staging (+ cleanup first)
+npm run build:uat        # uat
+npm run build            # production (alias: build:production)
+```
+
+### Release version
+
+```bash
+npm run release          # patch bump + build
+npm run release:minor
+npm run release:major
+```
+
+### Typical developer workflow
+
+1. **Scaffold** with `npx create-mf-app …`
+2. **`npm install`** at monorepo root
+3. **`npm run local`** or **`npm run <your-module>`** for focused work
+4. Edit **`apps/<module>/src/`** — routes, pages, services
+5. Use **`corelib`** for shared UI, theme, RBAC (see below)
+6. **`npm run type-check`** / **`npm run lint`** before commit
+7. **`npm run build:production`** before deploy
+8. **`npm run federation:verify`** to check remoteEntry URLs
+
+### Add a new remote after scaffold
+
+Use the built-in MF CLI (recommended):
+
+```bash
+npm run mf -- generate app inventory
+# wires federation, port, mf.json, and npm scripts
+```
+
+Or copy an existing child app folder and update `mf.json`, `federation.config.ts`, host routes, and root `package.json` scripts manually.
+
+---
+
+## CLI reference (create-mf-app)
 
 ```bash
 npx create-mf-app <project-name> [options]
 ```
 
-Options:
+| Option | Description |
+|--------|-------------|
+| `--port=3001` | Dev/preview port (**single app / child mode only**) |
+| `--template=tsx\|jsx` | TypeScript or JavaScript |
+| `--typescript` | Alias for `--template=tsx` |
+| `--javascript` | Alias for `--template=jsx` |
+| `--type=parent\|child` | Monorepo or single app (default: `child`) |
+| `--children=billing,orders` | Child remote app **folder names** (parent mode, required) |
+| `--shared=corelib` | Shared federated lib folder name (default: `sharedlib`) |
+| `--docker=true\|false` | Generate Dockerfiles (default: `true`) |
+| `--federation=true\|false` | Module Federation (default: `true`) |
+| `-y`, `--yes` | Non-interactive (use defaults where applicable) |
+| `-h`, `--help` | Show help |
 
-- `--port=3001`
-- `--template=tsx|jsx`
-- `--typescript` (alias for `--template=tsx`)
-- `--javascript` (alias for `--template=jsx`)
-- `--type=parent|child`
-- `--children=billing,orders,analytics`
-- `--shared=sharedlib`
-- `--docker=true|false`
-- `--federation=true|false`
-- `-y`, `--yes`
-- `-h`, `--help`
+**Parent mode rules:**
 
-## Interactive flow
+- `main` is **always** created as the host — never pass it in `--children` or `--shared`
+- `--children` is **required** in parent mode (comma- or space-separated)
+- If `--shared` is omitted, generator uses `sharedlib`
+- Child names become **`apps/<name>/`** folders and **`npm run <name>`** scripts
 
-When running `npx create-mf-app`:
+**Interactive flow** (run without project name):
 
-- Project Name
-- Application Type (Parent / Child)
-- Child Applications (for parent)
-- Shared Applications (for parent)
-- Template (TSX / JSX)
-- Port
-- Module Federation (Yes/No)
-- Docker (Yes/No)
+1. Project name  
+2. Application type (parent / child)  
+3. Child applications (checkboxes: admin, qc, inventory, shopfloor)  
+4. Shared applications (comma-separated, default `sharedlib`)  
+5. Template (tsx / jsx)  
+6. Port  
+7. Module Federation on/off  
+8. Docker on/off  
 
-## Parent mode behavior
+---
 
-- `main` is mandatory and reserved as host.
-- `main` is auto-created and cannot be passed in `children` or `shared`.
-- If `--shared` is omitted in parent mode, generator auto-adds `sharedlib`.
-- Children can be passed comma-separated or space-separated.
+## Custom child & shared app names
 
-Example:
+Folder names are **entirely user-defined** via CLI flags:
 
 ```bash
-npx create-mf-app my-platform --type parent --children billing orders analytics --template tsx
+npx create-mf-app acme-platform \
+  --type=parent \
+  --children=invoicing,shipping,reports \
+  --shared=corelib \
+  --template=tsx
+```
+
+**Creates:**
+
+```text
+apps/main/
+apps/invoicing/      → npm run invoicing
+apps/shipping/       → npm run shipping
+apps/reports/        → npm run reports
+apps/corelib/
 ```
 
-You can use any project/module names (for example `billing`, `orders`, `analytics`) except reserved `main`.
+**Host routes** (auto-wired): `/invoicing/*`, `/shipping/*`, `/reports/*`
+
+**Rules for names:**
+
+- Letters, numbers, dashes only (`^[a-z0-9-]+$`)
+- Lowercase recommended (billing, not Billing)
+- Do not use `main` — reserved for host
+
+---
+
+## Enterprise platform flags
+
+Optional modules for **parent monorepos** (core modules are always included):
 
-## Generated parent structure
+| Flag | Generated module |
+|------|------------------|
+| `--auth` | OAuth/OIDC foundation in `apps/corelib/src/auth/` + `packages/auth-sdk` |
+| `--charts` | Chart widgets in `apps/corelib/src/charts/` |
+| `--storybook` | `.storybook/` + component stories |
+| `--monitoring` | Logger, telemetry, Sentry, audit in `apps/corelib/src/monitoring/` |
+| `--table` | Advanced `AppDataGrid` (on by default for parent workspaces) |
+| `--form-engine` | Schema-driven forms in `apps/corelib/src/form-engine/` |
+| `--i18n` | Lazy locales + RTL in `apps/corelib/src/i18n/` |
+| `--testing` | Vitest workspace + Playwright + Cypress configs |
+| `--pwa` | PWA manifest placeholder |
+| `--plugin-system` | Runtime plugin registry in `apps/corelib/src/plugins/` |
+
+**Always included** for federated parent workspaces (no flag needed):
+
+| Module | Location |
+|--------|----------|
+| Design tokens | `apps/corelib/src/tokens/` |
+| Layouts | `apps/corelib/src/layouts/` (Dashboard, Auth, Settings, Split, Fullscreen, Error) |
+| RBAC | `apps/corelib/src/permissions/` |
+| Federation registry | `apps/corelib/src/federation/` |
+| Command palette | `apps/corelib/src/command-palette/` (Ctrl+K) |
+| Production hardening | `apps/corelib/src/production/` (CSP, env validation, diagnostics) |
+| MF Platform CLI | `tools/mf-cli/` |
+| Project graph | `tools/project-graph/` |
+| Task runner + cache | `task-runner/` + `.mf/cache` |
+
+---
+
+## Generated monorepo structure
 
 ```text
 my-platform/
+├── mf.json                          # Workspace config (like nx.json)
 ├── apps/
-│   ├── main/
-│   ├── billing/
+│   ├── main/                        # Host shell (port 3000)
+│   ├── billing/                     # Child remote (your --children names)
 │   ├── orders/
-│   ├── analytics/
-│   └── corelib/
+│   └── corelib/                     # Shared federated library (--shared name)
 ├── packages/
 │   ├── shared-ui/
+│   ├── shared-auth/
 │   ├── shared-utils/
-│   └── shared-auth/
+│   ├── shared-config/
+│   ├── shared-hooks/
+│   ├── shared-services/
+│   ├── shared-security/
+│   ├── sdk-core/
+│   ├── api-client/
+│   ├── query-client/
+│   ├── websocket-sdk/
+│   └── auth-sdk/                    # with --auth
+├── tools/
+│   ├── mf-cli/                      # mf CLI (generate, graph, affected, …)
+│   └── project-graph/
+├── task-runner/
+├── plugins/
+├── devtools/
+├── runtime-config/
+├── templates/
+├── ai/
+├── governance/
+├── k8s/helm/mf-platform/
+├── docs/
 ├── scripts/
+├── .github/workflows/
 ├── docker-compose.yml
-├── .env
-├── package.json
+├── .env, .env.dev, .env.staging, .env.uat, .env.prod
 ├── live-reload.js
 ├── smart-build.js
-├── print-env.js
-└── README.md
+└── package.json                     # npm run local, npm run billing, …
 ```
 
-## Root workspace scripts (parent mode)
+---
 
-Generated root scripts include:
+## MF Platform CLI (inside generated projects)
 
-- `local`, `dev`, `dev:watch`, `dev:fast`, `dev:safe`
-- `build:local`, `build:dev`, `build:staging`, `build:uat`, `build:production`
-- app-specific scripts like `billing`, `orders`, `analytics`, `warehouse`
-- `watch:*`, `preview:*`, `watch:local:*`, `preview:local:*`
-- `release`, `release:minor`, `release:major`
+After scaffolding, use the **`mf`** CLI inside your monorepo:
 
-## Module Federation wiring
+```bash
+npm run mf -- <command>
+# or
+node tools/mf-cli/bin/mf.js <command>
+```
 
-Generator configures:
+### Generators
+
+| Command | Description |
+|---------|-------------|
+| `mf generate app <name>` | New MFE remote (`create-app`, `create-mfe`) |
+| `mf generate lib <name>` | Shared library package (`create-lib`) |
+| `mf generate plugin <name>` | Platform plugin (`create-plugin`) |
+| `mf generate page <name> [app]` | Route page (`create-page`) |
+| `mf generate layout <name>` | Layout component (`create-layout`) |
+| `mf generate feature <name>` | Feature module (`create-feature`) |
+| `mf generate component <name>` | UI component in shared-ui |
+| `mf generate dashboard <name>` | Dashboard module (`create-dashboard`) |
+| `mf generate workflow <name>` | Workflow module (`create-workflow`) |
+| `mf generate api-sdk <name>` | API SDK package (`create-api-sdk`) |
+| `mf generate table <name>` | AppTable scaffold (`create-table`) |
+| `mf generate form <name>` | Form engine scaffold (`create-form`) |
+| `mf generate auth <name>` | Auth provider scaffold (`create-auth`) |
+| `mf generate theme <name>` | Theme preset (`create-theme`) |
+
+### Orchestration
+
+| Command | Description |
+|---------|-------------|
+| `mf graph` | Export dependency graph to `tools/project-graph/graph-ui/graph.json` |
+| `mf graph --federation` | Federation-only graph |
+| `mf affected build` | Git-aware incremental build |
+| `mf affected test` | Run tests only on affected projects |
+| `mf affected lint` | Lint only affected projects |
+| `mf affected <target> --base=main` | Custom git base branch |
+| `mf run <project> [target]` | Run target on one project |
+| `mf build` | Build all projects (parallel) |
+| `mf test` | Test all projects |
+| `mf lint` | Lint all projects |
+| `mf serve` | Delegates to `npm run local` |
+| `mf release [patch\|minor\|major]` | Release workflow |
+
+### Federation & health
+
+| Command | Description |
+|---------|-------------|
+| `mf federation doctor` | Check host/remotes/shared lib wiring |
+| `mf federation graph` | Export federation dependency graph |
+| `mf federation sync` | Sync remote manifests from `mf.json` |
+| `mf doctor` | Workspace health (circular deps, boundaries, mf.json) |
+| `npm run federation:verify` | HEAD-check remoteEntry URLs (`MF_REMOTES` env) |
+
+### npm script shortcuts (generated)
+
+```json
+"mf": "node tools/mf-cli/bin/mf.js",
+"mf:graph": "node tools/mf-cli/bin/mf.js graph",
+"mf:affected": "node tools/mf-cli/bin/mf.js affected build",
+"mf:doctor": "node tools/mf-cli/bin/mf.js doctor",
+"mf:federation": "node tools/mf-cli/bin/mf.js federation doctor"
+```
 
-- `remoteEntry.js`
-- host remotes registration in `main`
-- remote exposes (`./App`)
-- shared singleton dependencies:
-  - `react`
-  - `react-dom`
-  - `react-router-dom`
+---
+
+## Using corelib (shared library)
+
+**corelib** (or your `--shared` name) is a **Module Federation remote** that exposes shared UI, config, and RBAC. Child remotes and the host import it at runtime.
+
+### Host (`apps/main`) — wrap shell with providers
+
+```tsx
+const AppConfigProvider = React.lazy(() => import("corelib/AppConfigProvider"));
+const AppNavbar = React.lazy(() => import("corelib/AppNavbar"));
+const AppSidebar = React.lazy(() => import("corelib/AppSidebar"));
+const EnterpriseSidebarNav = React.lazy(() => import("corelib/EnterpriseSidebarNav"));
+const RoleProvider = React.lazy(() => import("corelib/RoleProvider"));
+const CommandPalette = React.lazy(() => import("corelib/CommandPalette"));
+
+export default function App() {
+  return (
+    <React.Suspense fallback={<div>Loading…</div>}>
+      <AppConfigProvider>
+        <RoleProvider>
+          {/* navbar, sidebar, routes */}
+        </RoleProvider>
+      </AppConfigProvider>
+    </React.Suspense>
+  );
+}
+```
 
-### Sharedlib integration
+### Child remote — use shared badge, RBAC, tokens
+
+```tsx
+const SharedBadge = React.lazy(() => import("corelib/SharedBadge"));
+const RoleProvider = React.lazy(() => import("corelib/RoleProvider"));
+
+export default function App() {
+  return (
+    <div className="remote-shell">
+      <RoleProvider>
+        <SharedBadge />
+        <AppRouter />
+      </RoleProvider>
+    </div>
+  );
+}
+```
 
-- `corelib` exposes `./SharedBadge`
-- child apps consume `corelib/SharedBadge`
-- `main` app provides navbar + route-based remote loading:
-  - `/billing/*`
-  - `/orders/*`
-  - `/analytics/*`
-  - etc.
+### Available federation exports (corelib)
+
+| Export | Purpose |
+|--------|---------|
+| `./App` | Standalone corelib demo app |
+| `./AppConfigProvider` | Theme + MUI provider + CSS variables |
+| `./useAppConfig` | Hook: config, palette, shell colors, toggle theme |
+| `./AppNavbar`, `./AppSidebar`, `./ThemeToggle` | Shell UI |
+| `./EnterpriseSidebarNav` | Role-filtered sidebar menu |
+| `./RouteGuard`, `./RoleProvider`, `./usePermission` | RBAC |
+| `./CommandPalette` | Ctrl+K palette |
+| `./DashboardLayout` | Dashboard shell layout |
+| `./PermissionProvider`, `./FederationFallback` | Permissions + error UI |
+| `./designTokens` | Token registry |
+
+### TypeScript — add declarations in host/child
+
+Generated projects include `src/types/federation-remotes.d.ts` for remote module names. After adding new exposes, extend that file:
+
+```ts
+declare module "corelib/MyNewComponent" {
+  const Component: React.ComponentType;
+  export default Component;
+}
+```
 
-## Shared configuration system (enterprise)
+---
 
-For parent mode with shared app (for example `sharedlib` or `corelib`), generator scaffolds centralized runtime configuration:
+## Enterprise design system & theming
 
 ```text
-apps/sharedlib/src/config/
-├── AppConfigProvider.tsx
-├── configStore.ts
-├── defaultConfig.ts
-├── themeGenerator.ts
-├── useAppConfig.ts
-└── types.ts
+apps/corelib/src/
+├── tokens/                 # colors, spacing, typography, shadows, …
+├── config/
+│   ├── AppConfigProvider.tsx
+│   ├── themeGenerator.ts   # MUI theme from tokens
+│   ├── resolveTheme.ts     # contrast-safe shell colors
+│   ├── colorUtils.ts       # WCAG contrast helpers
+│   └── defaultConfig.ts    # enterprise-light / enterprise-dark presets
+├── layouts/
+├── permissions/
+├── shared-ui/
+└── …
 ```
 
-It powers:
+### Runtime theme in your components
 
-- branding and title settings
-- color and typography runtime changes
-- sidebar/navbar/layout toggles
-- dark/light mode switching
-- preset themes
-- import/export config JSON
-- localStorage persistence
+```tsx
+import { useAppConfig } from "corelib/useAppConfig";
 
-MUI settings page is generated at:
+function MyWidget() {
+  const { config, palette, shell, toggleColorMode } = useAppConfig();
+  return (
+    <div style={{ color: palette.textPrimary, background: palette.surface }}>
+      {config.appName}
+    </div>
+  );
+}
+```
 
-- `apps/sharedlib/src/pages/Settings/SettingsPage.tsx`
+**Features:**
 
-Main app exposes routes:
+- Enterprise-light / enterprise-dark presets + Azure, Atlassian, Linear-dark, etc.
+- Light/dark toggle with **full palette sync** (background + text together)
+- **Contrast-safe** navbar/sidebar text (no dark-on-dark)
+- CSS variables (`--ds-*`) applied to `document.documentElement`
+- Responsive collapsible sidebar (flex layout, no overlap)
+- MUI component overrides from design tokens
 
-- `/settings/theme`
-- `/settings/layout`
-- `/settings/branding`
+**Clear cached theme** (after upgrades or bad colors):
 
-Shared UI foundation is also generated:
+```js
+localStorage.removeItem('mf-enterprise-config')
+```
+
+Then hard-refresh the browser.
+
+---
+
+## Module Federation
+
+### Architecture
+
+```text
+┌─────────────────────────────────────────────────────────┐
+│  apps/main (host) :3000                                  │
+│  ├── loads corelib remote (shared UI, theme, RBAC)       │
+│  ├── loads billing remote on /billing/*                  │
+│  └── loads orders remote on /orders/*                    │
+└─────────────────────────────────────────────────────────┘
+         │ shared singletons: react, react-dom, MUI, …
+         ▼
+┌──────────────┐  ┌──────────────┐  ┌──────────────┐
+│ apps/billing │  │ apps/orders  │  │ apps/corelib │
+│   :3001      │  │   :3002      │  │   :3003      │
+└──────────────┘  └──────────────┘  └──────────────┘
+```
+
+### Shared dependency rules (important)
+
+The generator configures federation so **one React/MUI instance** is shared:
+
+**Host (`apps/main/federation.config.ts`):**
+
+- Provides shared deps with **exact semver** keys: `version: "19.0.0"` (not `^19.0.0`)
+- `singleton: true`, `import: true`
+
+**Remotes (children + corelib):**
+
+- Consume host share scope: `requiredVersion: "^19.0.0"`
+- `singleton: true`
+
+**Shared packages:** `react`, `react-dom`, `react-router-dom`, `@mui/material`, `@mui/icons-material`, `@emotion/react`, `@emotion/styled`, `@mui/x-data-grid`
+
+**After changing federation config:**
+
+```bash
+npm run build:local    # rebuild ALL apps
+npm run local          # restart
+```
+
+Use **hoisted install** (generated `.npmrc`: `install-strategy=hoisted`).
+
+### Remote URLs (local dev)
+
+Each app's `federation.config.ts` points to:
 
 ```text
-apps/sharedlib/src/shared-ui/
-├── AppButton/
-├── AppCard/
-├── AppDialog/
-├── AppTable/
-├── AppInput/
-├── AppNavbar/
-├── AppSidebar/
-└── ThemeProvider/
+http://localhost:<port>/assets/remoteEntry.js
 ```
 
-Additional enterprise placeholders are scaffolded (permissions, feature flags, plugin registry, route guard, error boundary, global snackbar, i18n starter, command palette, notification center, profile dropdown, analytics/audit placeholders).
+Match ports from root `.env` when customizing.
+
+---
+
+## SDK packages
+
+| Package | Purpose |
+|---------|---------|
+| `@<project>/sdk-core` | Trace IDs, error normalization |
+| `@<project>/api-client` | Axios wrapper, interceptors, API versioning |
+| `@<project>/auth-sdk` | Token refresh helpers (`--auth`) |
+| `@<project>/query-client` | Query key utilities |
+| `@<project>/websocket-sdk` | Reconnecting WebSocket |
+
+Import from workspace packages in apps via `file:../../packages/<name>` dependencies.
+
+---
+
+## Task runner & build cache
+
+```text
+task-runner/
+├── orchestrator.js      # Parallel execution, dependency-aware runs
+├── cache-engine.js      # Hash-based local cache
+├── executors/           # build, test, lint
+└── pipelines/           # default: build → test → lint
+```
+
+- Cache directory: `.mf/cache/` (gitignored)
+- Cache key: hash of project + target + inputs
+- CI: cache `.mf/cache` in pipeline for faster rebuilds
+
+---
+
+## Plugins & devtools
+
+**Plugins** (`plugins/*-plugin/`): register generators, executors, hooks (preBuild, postBuild, appCreated).
+
+**Devtools** (`devtools/`):
+
+- **Federation inspector** — inspect loaded remotes in browser
+- **Performance profiler** — Web Vitals + route transition timing
+- **MFE debugger** — `window.__MF_DEBUG__` remote load tracing
+- **Theme inspector** — CSS variable viewer
+- **Dependency viewer** — CLI dependency tree
+
+---
+
+## Runtime configuration
+
+```text
+runtime-config/
+├── tenant-config.js     # Multi-tenant SaaS configs
+├── manifest-loader.js   # CDN remote manifest fetch
+├── feature-flags.js     # Runtime feature toggles
+└── branding.js          # Dynamic logo/colors injection
+```
+
+---
+
+## Template marketplace
+
+Enterprise blueprints in `templates/`:
+
+| Template | Domain |
+|----------|--------|
+| `lims-template` | Laboratory Information Management |
+| `hms-template` | Healthcare Management |
+| `erp-template` | Enterprise Resource Planning |
+| `analytics-template` | Analytics dashboards |
+| `admin-template` | Admin portal |
+| `saas-template` | Multi-tenant SaaS |
+| `workflow-template` | Workflow automation |
+
+---
 
-## Template support
+## CI/CD & governance
 
-### TSX template
+**GitHub Actions:**
 
-- `App.tsx`, `main.tsx`, `vite.config.ts`, `tsconfig.json`
-- Type declaration files for federated remotes are generated automatically in parent mode
+- `.github/workflows/mf-platform-ci.yml` — doctor, affected lint/test/build, security audit
+- `.github/workflows/mf-affected-deploy.yml` — affected deploy on main
 
-### JSX template
+**Also generated:**
 
-- `App.jsx`, `main.jsx`, `vite.config.js`, `jsconfig.json`
+- `.gitlab-ci.yml`
+- `k8s/helm/mf-platform/` — Helm chart for host + remotes
+- `governance/module-boundaries.json` — import boundary rules
+- `governance/CODEOWNERS` — team ownership
+- `governance/dependency-rules.json` — license governance
 
-## Environment files
+**Deploy strategy:**
 
-Each app gets app-level `.env`:
+1. `mf affected build` on merge
+2. Upload `apps/*/dist` to CDN
+3. Host loads remote manifests at runtime
+4. Helm/Kubernetes for containerized host + ingress
+
+---
+
+## Code quality
+
+Generated parent workspaces include:
+
+| Script | Purpose |
+|--------|---------|
+| `npm run lint` / `lint:fix` | ESLint across apps + packages |
+| `npm run format` / `format:check` | Prettier |
+| `npm run stylelint` | CSS / SCSS |
+| `npm run type-check` | TypeScript every workspace app |
+| `npm run test` / `test:watch` / `test:ci` | Vitest + coverage |
+| `npm run cleanup` | lint:fix → imports → type-check |
+| `npm run analyze:bundle` | Rollup visualizer per app |
+| `npm run security:audit` | npm audit |
+| `npm run production:hygiene` | Fail on console/debugger in sources |
+
+Husky: lint-staged + type-check + tests on pre-commit; lint + tests on pre-push. Commitlint for Conventional Commits.
+
+---
+
+## Root workspace scripts
+
+### Full platform
+
+| Script | Purpose |
+|--------|---------|
+| `local` | **Main dev command** — build:local + watch + preview + live-reload (all apps) |
+| `dev` | print-env + parallel Vite dev servers |
+| `dev:watch` | Same as `local` |
+| `dev:fast` | dev build once + preview + live-reload |
+| `dev:safe` | production build + preview only |
+| `build` | Production build (runs cleanup first) |
+| `build:local` | localdev mode build for all apps |
+| `build:dev` / `build:staging` / `build:uat` | Environment-specific builds |
+| `watch:<app>` | Vite watch for one app |
+| `preview:<app>` | Vite preview for one app |
+| `release` / `release:minor` / `release:major` | Version bump + build |
+| `federation:verify` | Remote entry health check |
+| `mf`, `mf:graph`, `mf:affected`, `mf:doctor` | Platform CLI shortcuts |
+
+### Per-module dev (dynamic — one script per `--children` name)
+
+| Script | Apps included |
+|--------|----------------|
+| `npm run billing` | main + corelib + billing |
+| `npm run orders` | main + corelib + orders |
+| `npm run <child>` | main + corelib + `<child>` |
+| `npm run corelib` | main + corelib |
+
+Supporting scripts (auto-generated):
+
+- `build:local:<child>-only` — build subset for that scenario  
+- `watch:local:<child>-only` — watch subset  
+- `watch:local:<app>` / `preview:local:<app>` — per-app watch/preview in localdev mode  
+
+---
+
+## Docker & deployment
+
+- **Dockerfile** per app (Node 22 Alpine, healthcheck)
+- **docker-compose.yml** — all apps on mapped ports
+- **`.npmrc`** — `install-strategy=hoisted` for federation shared deps
+
+**Per-app environment:**
 
 ```env
 VITE_PORT=3001
@@ -206,44 +819,114 @@ VITE_APP_NAME=billing
 VITE_REMOTE_ENTRY=http://localhost:3001/assets/remoteEntry.js
 ```
 
-Parent workspace also gets root `.env` with all app ports/remote URLs.
+Root `.env` lists all app ports and remote URLs (`.env.dev`, `.env.staging`, `.env.uat`, `.env.prod` variants).
+
+```bash
+docker compose up --build
+```
+
+For container-to-container federation, replace `localhost` remote URLs with Docker service hostnames.
+
+---
+
+## Documentation in generated projects
 
-## Docker support
+| File | Contents |
+|------|----------|
+| `README.md` | Ports, quick start, Docker, quality scripts |
+| `docs/ENTERPRISE_ARCHITECTURE.md` | Design system, RBAC, federation, SDK, deployment |
+| `docs/PLATFORM_ARCHITECTURE.md` | MF CLI, graph, cache, plugins, CI/CD |
+| `mf.json` | Project registry, tags, federation config |
+| `templates/README.md` | Template marketplace usage |
+| `ai/README.md` | AI layer integration guide |
 
-- Dockerfile generated per app (if Docker enabled)
-- parent mode generates `docker-compose.yml`
+---
 
-## Node version requirement
+## Node version
 
-Generated projects use Vite 7. Use Node:
+Generated projects use **Vite 7**. Requires:
 
 - `>=20.19.0` or
-- `>=22.12.0` (recommended: Node 22)
+- `>=22.12.0` (**recommended: Node 22**)
 
-If using Node 18, Vite commands will fail.
+Node 18 will fail on Vite 7 commands.
+
+---
 
 ## Troubleshooting
 
-- **`"local" cannot be used as a mode name`**
-  - fixed by using `localdev` mode in generated scripts
-- **`useRoutes() may be used only in context of a <Router>`**
-  - fixed by sharing `react-router-dom` singleton in federation config
-- **MUI/CSS not applied across remotes**
-  - fixed by sharing `@mui/material`, `@mui/icons-material`, `@emotion/react`, and `@emotion/styled` as federation singletons
-- **`Cannot find module 'billing/App'` in TS**
-  - fixed via generated `.d.ts` federation module declarations in TSX parent apps
-- **`Task not found: live-reload`**
-  - fixed via generated root script `"live-reload": "node live-reload.js"`
-- **Install succeeded but Vite binary missing (`ERR_MODULE_NOT_FOUND ... vite/dist/node/cli.js`)**
-  - clean and reinstall in generated workspace:
-  ```bash
-  rmdir /s /q node_modules
-  del package-lock.json
-  npm cache verify
-  npm install
-  ```
-
-Published files:
-
-- `dist/`
-- `README.md`
+| Issue | Fix |
+|-------|-----|
+| `"local" cannot be used as a mode name` | Generator uses `localdev` mode in Vite scripts |
+| `useRoutes() may be used only in context of a <Router>` | Share `react-router-dom` as federation singleton |
+| MUI/CSS not applied across remotes | Share `@mui/material`, `@emotion/*` as singletons |
+| `Cannot find module 'billing/App'` | Add federation `.d.ts` declarations in host |
+| `Task not found: live-reload` | Root `"live-reload": "node live-reload.js"` |
+| Vite binary missing after install | Clean reinstall (see below) |
+| Sidebar overlaps main content | Use generated flex sidebar in corelib |
+| **Text invisible on dark header/sidebar** | Clear `localStorage` key `mf-enterprise-config`; hard refresh |
+| `provider support react(undefined)` / `useState` null | Rebuild all apps after federation config change; host uses exact `version: "19.0.0"`, remotes use `requiredVersion: "^19.0.0"` |
+| `ENOENT @mui/icons-material` in host | Hoisted install + federation shared versions on host |
+| Build error `Could not resolve enterpriseGlobalCss` | Update to latest `@multisystemsuite/create-mf-app` |
+
+**Clean reinstall:**
+
+```bash
+rmdir /s /q node_modules
+del package-lock.json
+npm cache verify
+npm install
+npm run build:local
+```
+
+**Reset theme cache:**
+
+```js
+localStorage.removeItem('mf-enterprise-config')
+```
+
+---
+
+## Develop & publish this package
+
+For **contributors** working on the CLI itself (this repo):
+
+```bash
+git clone https://github.com/your-org/create-mf-app
+cd create-mf-app
+npm install
+npm run build          # tsup → dist/
+npm run dev            # run dist/index.js locally
+
+# test code changes
+node dist/index.js test-app --type=child --port=3001 --template=tsx
+
+# dry-run npm pack contents
+npm run pack:check
+
+# publish to npm (maintainers)
+npm run rebuild
+npm publish --access public
+```
+
+**Package name:** `@multisystemsuite/create-mf-app`  
+**Binary:** `create-mf-app`  
+**Published files:** `dist/`, `README.md`
+
+---
+
+## Summary
+
+| Layer | How you use it |
+|-------|----------------|
+| **Scaffold** | `npx create-mf-app <name> --type=parent --children=… --shared=corelib` |
+| **Daily dev** | `npm run local` (all apps) or `npm run billing` (one module) |
+| **Shared UI / theme** | Import from `corelib/*` federation exposes |
+| **New remote** | `npm run mf -- generate app <name>` |
+| **Enterprise modules** | Flags: `--auth`, `--charts`, `--i18n`, … |
+| **Monorepo platform** | `mf graph`, `mf affected build`, `mf doctor` |
+| **Federation** | Host :3000 loads remotes; shared React/MUI singletons |
+| **Design system** | `AppConfigProvider` + tokens + runtime theme toggle |
+| **Deploy** | `npm run build` → CDN dist + Helm / Docker |
+
+**Module Federation + Vite — React-first, enterprise-grade, plugin-driven.**