@bleedingdev/modern-js-create 3.2.0-ultramodern.8 → 3.2.0-ultramodern.80

package/README.md

@@ -12,85 +12,125 @@
 
 Please follow [Quick Start](https://modernjs.dev/en/guides/get-started/quick-start) to get started with Modern.js.
 
-For UltraModern.js, use the BleedingDev create package. It defaults to the
-canonical SuperApp workspace and published BleedingDev package aliases:
+For UltraModern.js, use the BleedingDev create package. It defaults to a
+production-ready single app with `presetUltramodern(...)`, TanStack Router,
+Tailwind CSS v4, i18n, Effect BFF, generated quality gates, and published
+BleedingDev package aliases:
 
 ```bash
-pnpm dlx @bleedingdev/modern-js-create my-super-app
+pnpm dlx @bleedingdev/modern-js-create my-app
 ```
 
-### Router Template
+To initialize the empty directory you are already in, pass `.` explicitly:
 
-You can scaffold a TanStack Router first template:
+```bash
+pnpm dlx @bleedingdev/modern-js-create .
+```
+
+Create a full SuperApp workspace only when you need independently owned
+verticals:
 
 ```bash
-npx @modern-js/create my-app --router tanstack
+pnpm dlx @bleedingdev/modern-js-create my-super-app --ultramodern-workspace
 ```
 
-### Tailwind Template
+The workspace is a full-stack reference, not a visual-only commerce boundary
+demo. It generates:
 
-You can scaffold Tailwind CSS v4 setup (PostCSS + starter utility classes):
+- `apps/shell-super-app` as the Module Federation host and topology owner.
+- `verticals/explore` for discovery UI plus
+  `/explore-api/effect/explore/*`.
+- `verticals/decide` for product selection UI plus
+  `/decide-api/effect/decide/*`.
+- `verticals/checkout` for cart and checkout UI plus
+  `/checkout-api/effect/checkout/*`.
+- `packages/shared-design-tokens` as the shared CSS token owner.
+- `.modernjs/ultramodern-generated-contract.json` with MF, Effect, i18n,
+  federated CSS, Cloudflare, and Zephyr dependency metadata.
+
+Validate the generated workspace before making application changes:
 
 ```bash
-npx @modern-js/create my-app --tailwind
+cd my-super-app
+mise install
+pnpm install
+pnpm ultramodern:check
+pnpm build
 ```
 
-You can combine both options:
+### Router Template
+
+TanStack Router is generated by default. To force the compatibility router:
 
 ```bash
-npx @modern-js/create my-app --router tanstack --tailwind
+pnpm dlx @bleedingdev/modern-js-create my-app --router react-router
 ```
 
-### BFF Runtime Template
+### Tailwind Template
 
-You can scaffold BFF APIs with the current default runtime:
+Tailwind CSS v4 setup is generated by default. Disable it explicitly when you
+need a plain CSS starter:
 
 ```bash
-npx @modern-js/create my-app --bff
+pnpm dlx @bleedingdev/modern-js-create my-app --no-tailwind
 ```
 
-You can explicitly scaffold Effect HttpApi runtime for BFF:
+TanStack Router and Tailwind CSS work together without extra flags:
 
 ```bash
-npx @modern-js/create my-app --bff-runtime effect
+pnpm dlx @bleedingdev/modern-js-create my-app
+```
+
+### BFF Runtime Template
+
+UltraModern app scaffolds include Effect HttpApi BFF by default:
+
+```bash
+pnpm dlx @bleedingdev/modern-js-create my-app
 ```
 
 To scaffold Hono runtime explicitly:
 
 ```bash
-npx @modern-js/create my-app --bff-runtime hono
+pnpm dlx @bleedingdev/modern-js-create my-app --bff-runtime hono
 ```
 
 Generated starters expose `presetUltramodern(...)` as the public opinionated
 config wrapper when you want the full Ultramodern setup surface in
 `modern.config.ts`.
 
-You can combine TanStack Router + Tailwind + Effect BFF in one command:
+TanStack Router, default Tailwind, and Effect BFF are included without extra
+flags. For local monorepo dependency testing, add `--workspace`:
 
 ```bash
-npx @modern-js/create my-app --router tanstack --tailwind --bff-runtime effect
+pnpm dlx @bleedingdev/modern-js-create my-app --workspace
 ```
 
-### Micro Vertical Workspace Recipes
+### Vertical Workspace Recipes
 
-Use the existing create flags to scaffold packages inside a Micro Vertical
-workspace. The shell and remotes use TanStack Router; services use Effect by
-default, with Hono kept as an explicit compatibility lane.
+Use the workspace add flow from the UltraModern workspace root. It derives the
+package path, package name, port, Module Federation name, topology entry, local
+overlay, ownership entry, Effect BFF surface, and root `dev:*` script from the
+requested vertical name.
 
 ```bash
-npx @modern-js/create apps/shell --router tanstack --tailwind --workspace --sub
-npx @modern-js/create apps/remotes/catalog --router tanstack --tailwind --workspace --sub
-npx @modern-js/create apps/remotes/design-system --router tanstack --tailwind --workspace --sub
-npx @modern-js/create services/catalog-api --bff-runtime effect --workspace --sub
-npx @modern-js/create services/legacy-api --bff-runtime hono --workspace --sub
+pnpm dlx @bleedingdev/modern-js-create catalog --vertical
 ```
 
-When a design system needs independent deployment, treat it as a horizontal
-Module Federation remote with the same topology, trust, SSR, compatibility, and
-fallback expectations as feature remotes. Otherwise shared packages should be
-regular workspace packages for tokens, primitives, generated clients, or
-domain-neutral utilities. Keep feature composites and workflow logic owned by a
-shell, remote, or service package.
+Use this decision table before adding a vertical:
+
+| Need | Keep inside current vertical | Create a new vertical |
+| --- | --- | --- |
+| Route or widget changes with the same product owner, release train, and fallback behavior | Yes | No |
+| Route subtree needs independent rollout, rollback, or incident ownership | No | `--vertical` |
+| UI and Effect BFF must version, deploy, and roll back together | No | `--vertical` |
+| Design tokens, primitives, generated clients, or domain-neutral utilities | Yes | Use an ordinary workspace package, not a vertical |
+| Feature composites or workflow state shared across verticals | No | Revisit ownership; do not hide it in shared code |
+
+The lower-level `--router`, `--workspace`, and `--sub` flags remain available
+for manual package scaffolding, but UltraModern vertical additions should use
+`--vertical` so paths, topology, Effect BFF contracts, and local overlays stay
+consistent.
 
 See
 `docs/super-app-rfc-adr/WORKSPACE-0001-micro-vertical-workspace-scaffolding.md`
@@ -101,13 +141,81 @@ UltraModern.js entrypoint. The lower-level `--ultramodern-*` flags remain
 available for release engineering and local package-source testing, but users
 should not need them for normal app creation.
 
+### Tractor Architecture Contracts
+
+The generated shell owns route assembly and policy. The generated Explore,
+Decide, and Checkout verticals own their own route subtree, MF exposes, Effect BFF
+contract, generated client, `localisedUrls`, locale JSON, CSS layer, and
+Cloudflare Worker output. The shell consumes vertical UI through MF manifests
+and vertical APIs through generated Effect clients exported by the vertical
+packages.
+
+Route localization is route-owned. Each app writes
+`src/routes/ultramodern-route-metadata` and passes
+`ultramodernLocalisedUrls` into `@modern-js/plugin-i18n`. Locale JSON is served
+from `/locales/{{lng}}/{{ns}}.json`; Czech and English routes are generated from
+the route owner, not from shell rewrites.
+
+CSS federation is explicit:
+
+- `packages/shared-design-tokens` exports `./tokens.css` and owns
+  `ultramodern-shared-tokens`.
+- The shell owns shell base and overlay CSS only.
+- Verticals own their vertical CSS layer and `[data-app-id="<vertical>"]`
+  root marker.
+- Tailwind CSS v4 is configured per app through `@tailwindcss/postcss`.
+- Duplicate base styles are forbidden; SSR first paint depends on shared token
+  CSS plus Modern/Rspack-emitted app CSS.
+- Apps should not inject remote `async-index.css` paths, hardcode remote
+  stylesheet links, or disable filename hashing to make CSS URLs predictable.
+  UltraModern SSR resolves federated CSS from build output and MF manifests so
+  generated shells and demos can keep normal hashed assets.
+
+Version switching evidence must keep UI, Effect API, CSS, i18n JSON, and MF
+manifest markers in lockstep for the same vertical version.
+
+### Cloudflare And Zephyr Proof
+
+Each generated app has:
+
+- `cloudflare:build`, `cloudflare:deploy`, `cloudflare:preview`, and
+  `cloudflare:proof` scripts.
+- Cloudflare metadata in `.modernjs/ultramodern-generated-contract.json`.
+- `zephyr:dependencies` for any consumed verticals.
+- `zephyr-rspack-plugin` wired through the generated Modern.js Rspack bridge.
+
+Public URL proof is intentionally separate from local build validation:
+
+```bash
+ULTRAMODERN_PUBLIC_URL_EXPLORE=https://explore.example.workers.dev \
+ULTRAMODERN_PUBLIC_URL_DECIDE=https://decide.example.workers.dev \
+ULTRAMODERN_PUBLIC_URL_CHECKOUT=https://checkout.example.workers.dev \
+ULTRAMODERN_PUBLIC_URL_SHELL_SUPER_APP=https://shell-super-app.example.workers.dev \
+pnpm cloudflare:proof -- --require-public-urls
+```
+
+Live Zephyr switching proof requires Zephyr credentials and public runtime,
+manifest, and API URLs for v1 and v2 of Explore, Decide, and Checkout. Without
+public URLs and credentials, use dry-run evidence only; do not claim live
+Zephyr selection has been proven.
+
 ### Local Monorepo Testing
 
 When testing unreleased Modern.js packages from a local monorepo checkout, use
 workspace protocol dependencies:
 
 ```bash
-npx @modern-js/create my-app --router tanstack --bff-runtime effect --workspace
+pnpm dlx @bleedingdev/modern-js-create my-app --workspace
+```
+
+For package-source validation of the full Tractor workspace, generate with the
+workspace package source, then run the generated contract gate:
+
+```bash
+pnpm dlx @bleedingdev/modern-js-create tractor-super-app --ultramodern-workspace --ultramodern-package-source workspace
+cd tractor-super-app
+pnpm install
+pnpm ultramodern:check
 ```
 
 ## Documentation