@bleedingdev/modern-js-create 3.2.0-ultramodern.7 → 3.2.0-ultramodern.70

package/README.md

@@ -13,12 +13,36 @@
 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:
+canonical Tractor SuperApp workspace and published BleedingDev package aliases:
 
 ```bash
 pnpm dlx @bleedingdev/modern-js-create my-super-app
 ```
 
+The default workspace is a full-stack reference, not a visual-only commerce
+boundary demo. It generates:
+
+- `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
+cd my-super-app
+mise install
+pnpm install
+pnpm ultramodern:check
+pnpm build
+```
+
 ### Router Template
 
 You can scaffold a TanStack Router first template:
@@ -29,16 +53,17 @@ npx @modern-js/create my-app --router tanstack
 
 ### Tailwind Template
 
-You can scaffold Tailwind CSS v4 setup (PostCSS + starter utility classes):
+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 --tailwind
+npx @modern-js/create my-app --no-tailwind
 ```
 
-You can combine both options:
+TanStack Router and Tailwind CSS work together without extra flags:
 
 ```bash
-npx @modern-js/create my-app --router tanstack --tailwind
+npx @modern-js/create my-app --router tanstack
 ```
 
 ### BFF Runtime Template
@@ -65,32 +90,37 @@ 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:
+You can combine TanStack Router + default Tailwind + Effect BFF in one command:
 
 ```bash
-npx @modern-js/create my-app --router tanstack --tailwind --bff-runtime effect
+npx @modern-js/create my-app --router tanstack --bff-runtime effect
 ```
 
-### 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
+npx @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,6 +131,64 @@ 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
@@ -110,6 +198,16 @@ workspace protocol dependencies:
 npx @modern-js/create my-app --router tanstack --bff-runtime effect --workspace
 ```
 
+For package-source validation of the full Tractor workspace, generate with the
+workspace package source, then run the generated contract gate:
+
+```bash
+npx @modern-js/create tractor-super-app --workspace
+cd tractor-super-app
+pnpm install
+pnpm ultramodern:check
+```
+
 ## Documentation
 
 - [English Documentation](https://modernjs.dev/en/)