@bleedingdev/modern-js-create 3.2.0-ultramodern.99 → 3.4.0-ultramodern.0

package/dist/types/ultramodern-workspace/types.d.ts

@@ -0,0 +1,197 @@
+import type { ResolvedUltramodernPackageSource, UltramodernPackageSourceStrategy } from '../ultramodern-package-source';
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type JsonObject = {
+    [key: string]: JsonValue;
+};
+export type RouteJsonLd = JsonObject | JsonObject[];
+export declare function sortJsonValue(value: JsonValue): JsonValue;
+export type WorkspaceApp = {
+    id: string;
+    directory: string;
+    packageSuffix: string;
+    displayName: string;
+    kind: 'shell' | 'vertical';
+    domain?: string;
+    portEnv: string;
+    port: number;
+    mfName: string;
+    exposes?: Record<string, string>;
+    effectApi?: WorkspaceEffectApi;
+    verticalRefs?: string[];
+    ownership: Ownership;
+};
+export type WorkspaceEffectApi = {
+    stem: string;
+    prefix: string;
+    consumedBy: string[];
+};
+export type ResolvedPackageSource = ResolvedUltramodernPackageSource;
+export type Ownership = {
+    team: string;
+    slack: string;
+    pagerDuty: string;
+    runbookRef: string;
+    adrRef: string;
+    blastRadius: {
+        tier: string;
+        references: string[];
+    };
+};
+export declare const supportedWorkspaceLanguages: readonly ['en', 'cs'];
+export type SupportedWorkspaceLanguage = (typeof supportedWorkspaceLanguages)[number];
+export type RoutePublicSurface = 'private-app-screen' | 'generated-public-surface' | 'explicit-public-input';
+export type RouteOwnedI18nPath = {
+    id: string;
+    canonicalPath: string;
+    localisedPaths: Record<SupportedWorkspaceLanguage, string>;
+    titleKey: string;
+    descriptionKey: string;
+    ownerAppId: string;
+    mfBoundaryId: string;
+    namespace: string;
+    public: boolean;
+    indexable: boolean;
+    publicSurface: RoutePublicSurface;
+    jsonLd?: RouteJsonLd;
+};
+export type PublicRouteMetadata = {
+    canonicalPath: string;
+    id: string;
+    localisedPaths: Record<SupportedWorkspaceLanguage, string>;
+    namespace: string;
+    ownerAppId: string;
+    titleKey: string;
+    descriptionKey: string;
+    jsonLd?: RouteJsonLd;
+};
+export type PublicSitemapChangeFrequency = 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';
+export type PublicSurfaceSitemapFields = {
+    lastModified?: string;
+    changeFrequency?: PublicSitemapChangeFrequency;
+    priority?: number;
+};
+export type UltramodernWorkspaceOptions = {
+    targetDir: string;
+    packageName: string;
+    modernVersion: string;
+    enableTailwind?: boolean;
+    overlays?: UltramodernCodeSmithOverlay[];
+    packageSource?: {
+        strategy?: UltramodernPackageSourceStrategy;
+        modernPackageVersion?: string;
+        registry?: string;
+        aliasScope?: string;
+        aliasPackageNamePrefix?: string;
+    };
+};
+export type AddUltramodernVerticalOptions = {
+    workspaceRoot: string;
+    name: string;
+    modernVersion: string;
+    enableTailwind?: boolean;
+    overlays?: UltramodernCodeSmithOverlay[];
+    packageSource?: UltramodernWorkspaceOptions['packageSource'];
+};
+export type UltramodernGenerationOperation = 'workspace' | 'vertical';
+/**
+ * Stable public descriptor for an app created by the UltraModern generator.
+ * Existing fields keep their meaning across patch/minor releases; new fields
+ * may be added as the generator records more contract data.
+ */
+export type UltramodernGeneratedAppDescriptor = {
+    id: string;
+    directory: string;
+    packageName: string;
+    packageSuffix: string;
+    displayName: string;
+    kind: WorkspaceApp['kind'];
+    portEnv: string;
+    port: number;
+    moduleFederationName: string;
+    exposes?: Record<string, string>;
+    effectApiPrefix?: string;
+};
+/**
+ * Stable public warning shape for non-fatal generator decisions.
+ */
+export type UltramodernGenerationWarning = {
+    code: string;
+    message: string;
+    path?: string;
+};
+/**
+ * Stable public result returned by workspace generation and MicroVertical
+ * addition. The CLI ignores this object, but automation can use it instead of
+ * re-reading the workspace to discover generated paths and integration data.
+ */
+export type UltramodernGenerationResult = {
+    operation: UltramodernGenerationOperation;
+    workspaceRoot: string;
+    packageScope: string;
+    packageSource: ResolvedPackageSource;
+    createdApps: UltramodernGeneratedAppDescriptor[];
+    createdPaths: string[];
+    rewrittenPaths: string[];
+    assignedPorts: Record<string, number>;
+    moduleFederationNames: Record<string, string>;
+    effectApiPrefixes: Record<string, string>;
+    generatedContractPath: string;
+    warnings: UltramodernGenerationWarning[];
+};
+export type UltramodernCodeSmithOverlay = {
+    generator: string;
+    config?: Record<string, unknown>;
+};
+export type UltramodernCodeSmithOverlayRuntimeConfig = {
+    workspaceRoot: string;
+    packageScope: string;
+    operation: UltramodernGenerationOperation;
+    generatedApp?: UltramodernGeneratedAppDescriptor;
+    generatedApps: UltramodernGeneratedAppDescriptor[];
+    assignedPort?: number;
+    assignedPorts: Record<string, number>;
+    moduleFederationName?: string;
+    moduleFederationNames: Record<string, string>;
+    effectApiPrefix?: string;
+    effectApiPrefixes: Record<string, string>;
+    packageSource: ResolvedPackageSource;
+    generationResult: UltramodernGenerationResult;
+};
+export type UltramodernJsonMutation = {
+    path: string;
+    pointer: string;
+    description: string;
+    value?: JsonValue;
+};
+export type UltramodernShellDependencyChange = {
+    path: string;
+    section: 'dependencies' | 'zephyr:dependencies';
+    packageName: string;
+    version: string;
+};
+export type UltramodernGeneratedContractChange = {
+    path: string;
+    addedAppIds: string[];
+    shellVerticalRefs: string[];
+};
+/**
+ * Stable public dry-run result for MicroVertical addition. It includes the
+ * same operation summary as a real add, plus planned JSON mutations and
+ * integration metadata that automation can inspect before writing files.
+ */
+export type UltramodernVerticalPlan = UltramodernGenerationResult & {
+    dryRun: true;
+    selectedPort: number;
+    moduleFederationRemote: {
+        id: string;
+        name: string;
+        manifestUrl: string;
+    };
+    effectApiPrefix?: string;
+    jsonMutations: UltramodernJsonMutation[];
+    shellDependencyChanges: UltramodernShellDependencyChange[];
+    generatedContractChanges: UltramodernGeneratedContractChange[];
+};
+export declare function isRecord(value: unknown): value is Record<string, JsonValue>;

package/dist/types/ultramodern-workspace/versions.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Every version pin and skill-repo commit hash baked into generated
+ * UltraModern workspaces lives here. Values must stay in lockstep with the
+ * checked-in templates under templates/ and template-workspace/.
+ */
+export declare const TANSTACK_ROUTER_VERSION = "1.170.16";
+export declare const MODULE_FEDERATION_VERSION = "2.6.0";
+export declare const ZEPHYR_RSPACK_PLUGIN_VERSION = "1.1.1";
+export declare const ZEPHYR_AGENT_VERSION = "1.1.1";
+export declare const WRANGLER_VERSION = "4.102.0";
+export declare const CLOUDFLARE_COMPATIBILITY_DATE = "2026-06-02";
+export declare const TAILWIND_VERSION = "4.3.1";
+export declare const TAILWIND_POSTCSS_VERSION = "4.3.1";
+export declare const POSTCSS_VERSION = "8.5.15";
+export declare const EFFECT_TSGO_VERSION = "0.14.6";
+export declare const TYPESCRIPT_STABLE_VERSION = "6.0.3";
+export declare const TYPESCRIPT_7_VERSION = "7.0.1-rc";
+export declare const TYPESCRIPT_VERSION = "7.0.1-rc";
+export declare const TYPESCRIPT_NATIVE_PREVIEW_VERSION = "7.0.0-dev.20260624.1";
+export declare const OXLINT_VERSION = "1.71.0";
+export declare const OXFMT_VERSION = "0.55.0";
+export declare const ULTRACITE_VERSION = "7.8.3";
+export declare const LEFTHOOK_VERSION = "^2.1.9";
+export declare const I18NEXT_VERSION = "26.3.1";
+export declare const NODE_FETCH_VERSION = "^3.3.2";
+export declare const REACT_VERSION = "^19.2.7";
+export declare const REACT_DOM_VERSION = "^19.2.7";
+export declare const REACT_ROUTER_VERSION = "7.18.0";
+export declare const TYPES_REACT_VERSION = "^19.2.17";
+export declare const TYPES_REACT_DOM_VERSION = "^19.2.3";
+export declare const NODE_VERSION = "26.3.0";
+export declare const PNPM_VERSION = "11.9.0";
+export declare const RSTACK_AGENT_SKILLS_COMMIT = "61c948b42512e223bad44b83af4080eba48b2677";
+export declare const MODULE_FEDERATION_AGENT_SKILLS_COMMIT = "07bb5b6c43ad457609e00c081b72d4c42508ec76";
+export declare const ultramodernWorkspaceVersions: {
+    tanstackRouter: string;
+    moduleFederation: string;
+    tailwind: string;
+    tailwindPostcss: string;
+};

package/dist/types/ultramodern-workspace/workspace-scripts.d.ts

@@ -0,0 +1,10 @@
+import type { WorkspaceApp } from './types';
+export declare function createAssertMfTypesScript(remotes?: WorkspaceApp[]): string;
+export declare function createWorkspaceValidationScript(scope: string, enableTailwind: boolean, remotes?: WorkspaceApp[]): string;
+export declare function createWorkspaceI18nBoundaryValidationScript(): string;
+export declare function createPublicSurfaceAssetsScript(): string;
+export declare function createCloudflareProofHelperScript(): string;
+export declare function createCloudflareVersionProofScript(): string;
+export declare function createPerformanceReadinessConfigScript(): string;
+export declare function createPerformanceReadinessScript(): string;
+export declare function writeGeneratedWorkspaceScripts(targetDir: string, scope: string, enableTailwind: boolean, remotes?: WorkspaceApp[]): void;

package/dist/types/ultramodern-workspace/write-workspace.d.ts

@@ -0,0 +1,4 @@
+import type { ResolvedPackageSource, UltramodernGenerationResult, UltramodernWorkspaceOptions, WorkspaceApp } from './types';
+export declare function writeApp(targetDir: string, scope: string, app: WorkspaceApp, packageSource: ResolvedPackageSource, enableTailwind: boolean, remotes?: WorkspaceApp[]): void;
+export declare function writeSharedPackages(targetDir: string, scope: string): void;
+export declare function generateUltramodernWorkspace(options: UltramodernWorkspaceOptions): UltramodernGenerationResult;

package/package.json

@@ -21,27 +21,69 @@
   "engines": {
     "node": ">=20"
   },
-  "version": "3.2.0-ultramodern.99",
+  "version": "3.4.0-ultramodern.0",
   "types": "./dist/types/index.d.ts",
-  "main": "./dist/index.js",
+  "main": "./dist/esm-node/index.js",
   "bin": {
-    "create": "bin/run.js"
+    "create": "bin/run.js",
+    "modern-js-create": "bin/run.js"
+  },
+  "typesVersions": {
+    "*": {
+      ".": [
+        "./dist/types/index.d.ts"
+      ],
+      "ultramodern-workspace": [
+        "./dist/types/ultramodern-workspace/public-api.d.ts"
+      ],
+      "ultramodern-workspace/codesmith": [
+        "./dist/types/ultramodern-workspace/codesmith.d.ts"
+      ]
+    }
   },
   "exports": {
-    ".": "./dist/index.js"
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "node": {
+        "import": "./dist/esm-node/index.js",
+        "require": "./dist/cjs/index.cjs"
+      },
+      "default": "./dist/esm-node/index.js"
+    },
+    "./ultramodern-workspace": {
+      "types": "./dist/types/ultramodern-workspace/public-api.d.ts",
+      "node": {
+        "import": "./dist/esm-node/ultramodern-workspace/public-api.js",
+        "require": "./dist/cjs/ultramodern-workspace/public-api.cjs"
+      },
+      "default": "./dist/esm-node/ultramodern-workspace/public-api.js"
+    },
+    "./ultramodern-workspace/codesmith": {
+      "types": "./dist/types/ultramodern-workspace/codesmith.d.ts",
+      "node": {
+        "import": "./dist/esm-node/ultramodern-workspace/codesmith.js",
+        "require": "./dist/cjs/ultramodern-workspace/codesmith.cjs"
+      },
+      "default": "./dist/esm-node/ultramodern-workspace/codesmith.js"
+    }
   },
   "files": [
-    "template",
     "template-workspace",
+    "templates",
     "dist",
-    "bin.js"
+    "bin"
   ],
+  "dependencies": {
+    "@modern-js/codesmith": "2.6.9",
+    "@modern-js/i18n-utils": "npm:@bleedingdev/modern-js-i18n-utils@3.4.0-ultramodern.0"
+  },
   "devDependencies": {
-    "@rslib/core": "0.21.5",
-    "@types/node": "^25.9.1",
-    "@typescript/native-preview": "7.0.0-dev.20260527.2",
-    "tsx": "^4.22.3",
-    "@modern-js/i18n-utils": "npm:@bleedingdev/modern-js-i18n-utils@3.2.0-ultramodern.99"
+    "@rslib/core": "0.23.0",
+    "@types/node": "^26.0.0",
+    "@typescript/native-preview": "7.0.0-dev.20260624.1",
+    "tsx": "^4.22.4",
+    "typescript": "^6.0.3",
+    "@scripts/rstest-config": "2.66.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
@@ -49,11 +91,12 @@
   },
   "modern:source": "./src/index.ts",
   "scripts": {
-    "build": "rslib build && pnpm -w tsgo:dts \"$PWD\"",
-    "dev": "rslib build -w",
-    "start": "node ./dist/index.js"
+    "build": "rm -rf dist && rslib build -c rslibconfig.mts && pnpm -w tsgo:dts \"$PWD\"",
+    "dev": "rslib build -c rslibconfig.mts -w",
+    "start": "node ./dist/esm-node/index.js",
+    "test": "rm -rf dist && rslib build -c rslibconfig.mts && rstest --passWithNoTests"
   },
   "ultramodern": {
-    "frameworkVersion": "3.2.0-ultramodern.99"
+    "frameworkVersion": "3.4.0-ultramodern.0"
   }
 }

package/template-workspace/.github/workflows/ultramodern-workspace-gates.yml.handlebars

@@ -11,17 +11,33 @@ defaults:
   run:
     shell: bash
 
-env:
-  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
-
 concurrency:
   group: ultramodern-workspace-gates-${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
 jobs:
-  ultramodern-workspace-gates:
+  workspace-gate:
+    name: ${{ matrix.name }}
     runs-on: ubuntu-latest
     timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: Format
+            command: pnpm format:check
+          - name: Lint
+            command: pnpm lint
+          - name: Typecheck
+            command: pnpm typecheck
+          - name: Skills
+            command: pnpm skills:check
+          - name: I18n Boundaries
+            command: pnpm i18n:boundaries
+          - name: Contract
+            command: pnpm contract:check
+          - name: Build
+            command: pnpm build
     steps:
       - name: Harden Runner
         uses: step-security/harden-runner@ab7a9404c0f3da075243ca237b5fac12c98deaa5 # v2
@@ -37,7 +53,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
-          node-version: 24
+          node-version: "{{nodeVersion}}"
 
       - name: Setup mise
         uses: jdx/mise-action@5ac50f778e26fac95da98d50503682459e86d566 # v3.2.0
@@ -45,10 +61,7 @@ jobs:
       - name: Install Dependencies
         run: mise exec -- pnpm install --frozen-lockfile
 
-      - name: Validate Ultramodern Workspace Contract
-        run: mise exec -- pnpm run ultramodern:check
-
-      - name: Build Workspace Apps
+      - name: Run ${{ matrix.name }}
         env:
           MODERN_PUBLIC_SITE_URL: http://localhost:8080
-        run: mise exec -- pnpm build
+        run: mise exec -- ${{ matrix.command }}

package/template-workspace/.mise.toml.handlebars

@@ -1,2 +1,3 @@
 [tools]
+node = "{{nodeVersion}}"
 pnpm = "{{pnpmVersion}}"

package/template-workspace/{AGENTS.md → AGENTS.md.handlebars}

@@ -6,12 +6,20 @@ instructions, not optional reading.
 
 ## Quality Gates
 
+Generated workspaces target Node `>=26` and pnpm `{{pnpmVersion}}`. Keep
+`packageManager`, `.mise.toml`, generated validation, and CI aligned to that
+baseline; do not reintroduce Corepack or older pnpm aliases.
+
 - `pnpm lint` runs Oxlint with the Ultracite preset.
 - `pnpm format` runs oxfmt.
 - `pnpm typecheck` runs effect-tsgo as the TypeScript checker.
-- `pnpm check` runs formatting, linting, effect-tsgo, private-skill availability checks, and the generated workspace contract.
+- `pnpm i18n:boundaries` verifies workspace source boundaries through `@modern-js/code-tools`.
+- `pnpm contract:check` verifies the generated workspace contract.
+- `pnpm mf:types` verifies Module Federation type outputs after builds.
+- `pnpm check` is a local convenience aggregate for the primitive gates.
+- Generated CI runs primitive gates as separate matrix jobs instead of calling `pnpm check`.
 - Generated Codex stop hooks and subagent-stop hooks run `pnpm format && pnpm lint:fix && pnpm check`.
-- `postinstall` formats the generated tree, initializes Git when needed, installs agent skills and reference repos, then installs `lefthook`. Generated `lefthook.yml` runs `pnpm format && pnpm lint:fix && pnpm check` on pre-commit; pre-push runs `pnpm check`.
+- `postinstall` formats the generated tree and installs `lefthook`. It never clones repositories or installs system packages; agent skill repos and reference repos are explicit opt-in steps (`pnpm skills:install`, `pnpm agents:refs:install`). Generated `lefthook.yml` runs separate format and lint-fix commands on pre-commit; pre-push runs read-only primitive gates in parallel.
 
 ## Localized Routes
 
@@ -20,9 +28,12 @@ static language links, and canonical plus `hreflang` metadata. A new workspace
 starts shell-only; `create <domain> --vertical` adds route-owned metadata,
 localized resources, and Effect BFF surfaces for that domain. Runtime i18n is
 not enabled in the starter because the current React 19 + Module Federation
-streaming SSR stack must render predictably first. Production builds fail unless
-`MODERN_PUBLIC_SITE_URL` is set per deployed app, so canonical URLs always use
-the production origin.
+streaming SSR stack must render predictably first. Canonical and hreflang URLs
+use `MODERN_PUBLIC_SITE_URL` only. JS/CSS/static assets use
+`MODERN_ASSET_PREFIX`, then `ULTRAMODERN_ASSET_PREFIX`, then `/`; do not use
+`MODERN_PUBLIC_SITE_URL` or stale public URL aliases as asset-prefix fallbacks.
+Without an asset prefix, builds emit origin-relative asset paths so pages work
+behind tunnels and reverse proxies.
 
 ## Required Skill Baseline
 
@@ -37,7 +48,7 @@ Use these skills when the task touches the matching subsystem:
 - `rstest-best-practices`: Rstest configuration, test writing, mocking, snapshots, coverage, and CI test behavior.
 - `mf`: Module Federation docs, Modern.js integration, DTS/type checks, shared dependency checks, runtime errors, and observability troubleshooting.
 
-The public `module-federation/agent-skills` repository is installed during `pnpm install` and `pnpm skills:install`. `pnpm skills:check` fails when the required public `mf` skill is missing.
+The public `module-federation/agent-skills` repository is installed only when you explicitly run `pnpm skills:install` (or set `ULTRAMODERN_AGENT_SKILLS=1` before `pnpm install`). Postinstall never clones repositories. `pnpm skills:install` remains strict for required public skills. `pnpm skills:check` fails when a vendored skill is missing and warns when clone-installed skills such as `mf` have not been fetched yet.
 
 ## Private Skills
 
@@ -51,12 +62,12 @@ The installer copies only the pinned private skills from `.agents/skills-lock.js
 
 ## Agent Reference Repositories
 
-The workspace installs read-only source references under `repos/` by default during `pnpm install` using `git subtree add --squash`. These repositories are reference material for coding agents, not application source:
+The workspace can install read-only source references under `repos/` with the explicit `pnpm agents:refs:install` command using `git subtree add --squash`. These repositories are reference material for coding agents, not application source:
 
 - `repos/effect` from `Effect-TS/effect`.
 - `repos/ultramodern.js` from `BleedingDev/ultramodern.js`.
 
-Agents may read files under `repos/` to understand upstream patterns, APIs, and project conventions. Do not edit files under `repos/`, import from them, or make production code depend on them. To skip this setup, run installs with `ULTRAMODERN_SKIP_AGENT_REPOS=1`.
+Agents may read files under `repos/` to understand upstream patterns, APIs, and project conventions. Do not edit files under `repos/`, import from them, or make production code depend on them. `ULTRAMODERN_SKIP_AGENT_REPOS=1` disables the installer even when invoked explicitly.
 
 ## Project Priorities
 
@@ -73,4 +84,4 @@ Agents may read files under `repos/` to understand upstream patterns, APIs, and
 
 ## Skill Provenance
 
-The vendored Rstack skills, public Module Federation skill, and private TechsioCZ skill set are pinned in `.agents/skills-lock.json`. Do not update, remove, or replace them casually. If a skill needs updating, update the lock file and run `pnpm check`.
+The vendored Rstack skills, public Module Federation skill, and private TechsioCZ skill set are pinned in `.agents/skills-lock.json`. Do not update, remove, or replace them casually. If a skill needs updating, update the lock file and run the affected primitive gate plus `pnpm check`.

package/template-workspace/README.md.handlebars

@@ -7,8 +7,8 @@ UltraModern.js 3.0 SuperApp surface and starts with an explicit shell:
 
 - `apps/shell-super-app` owns shell route assembly, Module Federation host
   wiring, shared SSR/i18n runtime setup, and the boundary debugger.
-- `packages/shared-*` provide placeholders for cross-workspace contracts,
-  design tokens, and Effect API sharing.
+- `packages/shared-*` provide placeholders for cross-workspace contracts and
+  design tokens.
 - `verticals/*` is intentionally empty until a real business domain is added.
 
 Add a full-stack MicroVertical when the product needs one:
@@ -19,9 +19,36 @@ pnpm dlx @bleedingdev/modern-js-create payments --vertical
 ```
 
 Each added vertical owns its UI/routes, browser-safe Module Federation exposes,
-localized route metadata, CSS prefix, Effect BFF handlers, local API contract,
-and typed client surface. Server handlers and Effect client/contract modules
-stay out of browser exposes.
+private-first route metadata, localized URLs, public-route opt-ins, CSS prefix,
+Effect BFF handlers, local API contract, and typed client surface. Server
+handlers and Effect client/contract modules stay out of browser exposes.
+
+## Private-First Public Surfaces
+
+Generated app routes are private and non-indexable by default. Author route
+metadata in colocated `src/routes/**/route.meta.ts` files; the scaffold
+regenerates `src/routes/ultramodern-route-metadata.ts` as a compatibility
+manifest for config, i18n, public head, and public surface contracts. Private
+app, auth, tenant, dashboard, and internal routes publish no discovery output
+unless route metadata explicitly marks them `public && indexable`. The default
+scaffold therefore emits only a disallowing `robots.txt`; sitemap, web
+manifest, `llms.txt`, API catalog, security.txt, and JSON-LD output stay
+omitted until a safe public route or public docs/help/product surface exists.
+Structured data is never inferred automatically. Add `jsonLd` explicitly in
+route metadata for `public && indexable` routes and use
+`src/routes/ultramodern-jsonld.ts` when the route fits the generated `WebPage`,
+`WebApplication`, `SoftwareApplication`, `BreadcrumbList`, `FAQPage`, or
+`Organization` helpers. Private or non-indexable routes emit no JSON-LD even
+when they have localized paths, titles, descriptions, BFF APIs, or Module
+Federation boundaries.
+
+Public web artifacts are build/deploy outputs generated into `dist/public` and
+`.output/public`, not hand-authored source files under `config/public`. Dynamic
+public routes can expand sitemap entries through route-owned, Node-safe
+`route.sitemap.mjs` providers beside route metadata. The public-surface
+generator discovers those providers for dynamic public routes and still honors
+explicit `routes.publicSurface.contentSources` entries in the generated
+compatibility manifest.
 
 Run the scaffold validator before adding business code and after every
 `--vertical` mutation:
@@ -33,11 +60,24 @@ pnpm check
 pnpm build
 ```
 
-By default, `pnpm install` also prepares read-only agent reference repositories
-under `repos/` for Effect and UltraModern.js source lookup using squashed git
-subtrees. Disable this setup with
-`ULTRAMODERN_SKIP_AGENT_REPOS=1 pnpm install`, or rerun it
-explicitly with `pnpm agents:refs:install`.
+The generated toolchain baseline is Node `>=26` with pnpm `{{pnpmVersion}}`.
+`packageManager`, `.mise.toml`, generated validation, and CI should all agree
+on that baseline; do not reintroduce Corepack or older pnpm aliases.
+
+Generated CI does not call the local aggregate. It runs format, lint,
+typecheck, skills, i18n boundary validation, contract validation, and build as
+separate matrix jobs so failures are isolated and parallelizable.
+
+Read-only agent reference repositories under `repos/` (Effect and
+UltraModern.js source lookup using squashed git subtrees) are an explicit
+opt-in step: run `pnpm agents:refs:install` when you want them. `pnpm install`
+never clones repositories.
+
+Vendored agent skills ship with the scaffold. Clone-installed skills (such as
+the Module Federation `mf` skill) are fetched only when you explicitly run
+`pnpm skills:install`, or when `ULTRAMODERN_AGENT_SKILLS=1` is set during
+`pnpm install`. `pnpm skills:check` warns about missing clone-installed skills
+without failing the gate.
 
 The topology and ownership metadata are generated under `topology/`. The
 workspace also ships `.github/workflows/ultramodern-workspace-gates.yml` and
@@ -53,12 +93,43 @@ development. To create a workspace that can install those packages outside the
 monorepo, generate with `--ultramodern-package-source install`; generated shared
 packages still use `workspace:*` because they are part of this workspace.
 
+## Public URL Environment Variables
+
+This workspace's apps must not bake absolute `http://localhost:<port>` URLs
+into asset configuration. Public URL and asset prefix environment variables
+have distinct roles, and stale aliases should not be carried forward when
+regenerating or updating the workspace.
+
+| Variable | Role | Feeds |
+| --- | --- | --- |
+| `MODERN_PUBLIC_SITE_URL` | Canonical site origin for public SEO output only | Canonical, hreflang, sitemap `<loc>`, robots `Sitemap:` |
+| `MODERN_ASSET_PREFIX` | Preferred JS/CSS/static asset prefix | Modern/Rspack-emitted asset URLs |
+| `ULTRAMODERN_ASSET_PREFIX` | UltraModern compatibility asset prefix | Modern/Rspack-emitted asset URLs when `MODERN_ASSET_PREFIX` is unset |
+| `ULTRAMODERN_PUBLIC_URL_<APP_ID>` | Per-app deployment/proof URL | Cloudflare proof inputs and Module Federation remote URLs |
+
+Asset URLs use this precedence: `MODERN_ASSET_PREFIX` →
+`ULTRAMODERN_ASSET_PREFIX` → origin-relative `/`. `MODERN_PUBLIC_SITE_URL` is
+canonical/SEO-only and must not be used as an asset-prefix fallback.
+SEO output uses `MODERN_PUBLIC_SITE_URL`; if it is unset, generated local and
+preview outputs remain non-public until deployment proof provides explicit
+public URLs.
+
+Without public URLs configured, asset paths are origin-relative (`/`), and the
+dev server uses `dev.assetPrefix: '/'` — so apps work through tunnels and
+reverse proxies (ngrok, cloudflared) without triggering Chrome's Local Network
+Access prompt or mixed-content errors. Shell-only workspaces can set
+`MODERN_PUBLIC_SITE_URL` for SEO output without changing where assets load
+from.
+
 ## Cloudflare Proof
 
 Deploy the generated apps, then pass each deployed app's generated public URL
-env key into the proof step. A shell-only workspace only needs the shell URL;
-added verticals use the same `ULTRAMODERN_PUBLIC_URL_<APP_ID>` pattern with
-hyphens converted to underscores and uppercased.
+env key into the proof step. The proof script reads the generated contract and
+checks the live Worker surface, including public-route sitemap/robots
+consistency, preview noindex behavior, unknown-route status, asset headers,
+byte budgets, and public sourcemap exposure. A shell-only workspace only needs
+the shell URL; added verticals use the same `ULTRAMODERN_PUBLIC_URL_<APP_ID>`
+pattern with hyphens converted to underscores and uppercased.
 
 ```bash
 pnpm cloudflare:deploy
@@ -72,7 +143,7 @@ pnpm cloudflare:proof -- --require-public-urls
 | --- | --- | --- |
 | Package cohort mismatch | Regenerate with one package source strategy, run `mise install`, then rerun `pnpm install` from the activated shell. | Generated workspace package source metadata |
 | Install failure | Check the active Node/pnpm from `mise install`; rerun `pnpm install` after the shell sees the pinned versions. | Toolchain setup |
-| Build failure | Run `pnpm check` before `pnpm build`; fix reported format, lint, type, skill, i18n, or generated-contract failures first. | Owning package or generated contract |
+| Build failure | Run the matching primitive gate (`pnpm lint`, `pnpm typecheck`, `pnpm i18n:boundaries`, `pnpm contract:check`) before `pnpm build`; fix the owning failure first. | Owning package or generated contract |
 | Missing public URL | Set the env key from `.modernjs/ultramodern-generated-contract.json`, for example `ULTRAMODERN_PUBLIC_URL_SHELL_SUPER_APP`. | Deployment operator |
 | Cloudflare credentials | Confirm Wrangler credentials before `pnpm cloudflare:deploy`; local checks do not prove live Worker access. | Deployment operator |
 | Asset or CSS 404 | Rebuild with `pnpm build` or `pnpm cloudflare:deploy` and inspect emitted Modern/Rspack asset paths instead of hardcoding CSS URLs. | Framework/runtime asset pipeline |

package/template-workspace/lefthook.yml

@@ -1,10 +1,24 @@
 pre-commit:
   commands:
-    fix-and-check:
-      run: pnpm format && pnpm lint:fix && pnpm check
+    format:
+      run: pnpm format
+      stage_fixed: true
+    lint-fix:
+      run: pnpm lint:fix
       stage_fixed: true
 
 pre-push:
+  parallel: true
   commands:
-    check:
-      run: pnpm check
+    format:
+      run: pnpm format:check
+    lint:
+      run: pnpm lint
+    typecheck:
+      run: pnpm typecheck
+    skills:
+      run: pnpm skills:check
+    i18n-boundaries:
+      run: pnpm i18n:boundaries
+    contract:
+      run: pnpm contract:check