@bleedingdev/modern-js-create 3.2.0-ultramodern.4 → 3.2.0-ultramodern.40

package/README.md

@@ -12,6 +12,37 @@
 
 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 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.
+- `apps/remotes/remote-explore` for discovery UI plus
+  `/explore-api/effect/explore/*`.
+- `apps/remotes/remote-decide` for product selection UI plus
+  `/decide-api/effect/decide/*`.
+- `apps/remotes/remote-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
+mise exec -- pnpm install
+mise exec -- pnpm ultramodern:check
+mise exec -- pnpm build
+```
+
 ### Router Template
 
 You can scaffold a TanStack Router first template:
@@ -22,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
@@ -58,26 +90,36 @@ 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
 
-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, and root `dev:*` script from the requested name and
+kind.
 
 ```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 --microvertical remote
+npx @modern-js/create design-system --microvertical horizontal-remote
+npx @modern-js/create catalog-api --microvertical service
+npx @modern-js/create catalog-contracts --microvertical shared
 ```
 
+Use this decision table before adding a package:
+
+| Need | Keep inside current vertical | Create a new vertical/package |
+| --- | --- | --- |
+| 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 | `--microvertical remote` |
+| Cross-vertical operation needs strict trace, auth, locale, and session propagation | No | `--microvertical service` |
+| Design tokens, primitives, generated clients, or domain-neutral utilities | No | `--microvertical shared` |
+| Feature composites or workflow state shared across verticals | No | Revisit ownership; do not hide it in `shared` |
+
 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
@@ -85,10 +127,73 @@ 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.
 
+The lower-level `--router`, `--workspace`, and `--sub` flags remain available
+for manual package scaffolding, but UltraModern MicroVertical additions should
+prefer `--microvertical` to avoid hand-writing workspace paths and topology
+metadata.
+
 See
 `docs/super-app-rfc-adr/WORKSPACE-0001-micro-vertical-workspace-scaffolding.md`
 for the canonical workspace topology and local orchestration model.
 
+The published `@bleedingdev/modern-js-create` package is the preferred
+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 remotes own their own route subtree, MF exposes, Effect BFF
+contract, generated client, `localisedUrls`, locale JSON, CSS layer, and
+Cloudflare Worker output. The shell consumes remote UI through MF manifests and
+remote APIs through generated Effect clients exported by the remote 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.
+- Vertical remotes own their remote CSS layer and `[data-app-id="<remote>"]`
+  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.
+
+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 remotes.
+- `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_REMOTE_EXPLORE=https://remote-explore.example.workers.dev \
+ULTRAMODERN_PUBLIC_URL_REMOTE_DECIDE=https://remote-decide.example.workers.dev \
+ULTRAMODERN_PUBLIC_URL_REMOTE_CHECKOUT=https://remote-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
@@ -98,6 +203,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
+mise exec -- pnpm install
+mise exec -- pnpm ultramodern:check
+```
+
 ## Documentation
 
 - [English Documentation](https://modernjs.dev/en/)