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

package/template-workspace/.agents/skills/rstest-best-practices/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: rstest-best-practices
+description: Rstest best practices for config, CLI workflow, test writing, mocking, snapshot testing, DOM testing, coverage, multi-project setup, CI integration, performance and debugging. Use when writing, reviewing, or troubleshooting Rstest test projects.
+---
+
+# Rstest Best Practices
+
+Apply these rules when writing or reviewing Rstest test projects.
+
+## Configuration
+
+- Use `rstest.config.ts` and `defineConfig` from `@rstest/core`
+- Prefer explicit imports `import { test, expect, describe } from '@rstest/core'` over `globals: true`
+- For Rsbuild projects, use `@rstest/adapter-rsbuild` with `extends: withRsbuildConfig()` to reuse build config
+- For Rslib projects, use `@rstest/adapter-rslib` with `extends: withRslibConfig()` to reuse build config
+- Use `setupFiles` for shared test setup (e.g., custom matchers, cleanup hooks)
+- When using Rsbuild plugins (e.g., `@rsbuild/plugin-react`), add them via the `plugins` field
+- For deep-level or advanced build configuration needs, use `tools.rspack` or `tools.bundlerChain`
+
+## CLI
+
+- Use `rstest` or `rstest run` to run tests (`run` disables watch mode, suitable for CI)
+- Use `rstest --watch` or `rstest watch` for local development with file watching
+- Use `rstest list` to list all test files and test names
+- Use `rstest -u` to update snapshots
+- Use `--reporter=verbose` when debugging test failures for detailed output
+- Use `--config` (`-c`) to specify a custom config file path
+
+## Test writing
+
+- Import test APIs from `@rstest/core`: `test`, `describe`, `expect`, `beforeEach`, `afterEach`, etc.
+- Use `test` or `it` for test cases; use `describe` for grouping related tests
+- Use `.only` to focus on specific tests during development, but never commit `.only` to the codebase
+- Use `.skip` or `.todo` to mark incomplete or temporarily skipped tests
+- Prefer small, focused test cases that test a single behavior
+- For async error paths, prefer `await expect(fn()).rejects.toThrow(ErrorClass)` (or `.rejects.toMatchObject({ ... })`) over `try/catch` with `expect.fail` or `.catch(e => e)` patterns — the matcher form fails clearly if the promise unexpectedly resolves, keeps the assertion in one chain, and avoids forgetting to assert the throw at all
+- For async happy paths, use `await expect(fn()).resolves.toEqual(...)` for the same reason
+- Use `includeSource` for in-source testing of small utility functions (Rust-style `import.meta.rstest`)
+- For in-source tests, wrap test code in `if (import.meta.rstest) { ... }` and define `import.meta.rstest` as `false` in production build config
+
+## Test environment
+
+- Use `testEnvironment: 'node'` (default) for Node.js / server-side code
+- Use `testEnvironment: 'jsdom'` or `testEnvironment: 'happy-dom'` for DOM / browser API testing
+- Install `jsdom` or `happy-dom` as a dev dependency when using DOM environments
+- Prefer `happy-dom` for faster DOM testing; use `jsdom` when better browser API compatibility is needed
+- For real browser testing, use `@rstest/browser` with Playwright
+- Use inline project configs to run different test environments within one project (e.g., `node` and `jsdom` projects)
+
+## React / Vue testing
+
+- For React: use `@rsbuild/plugin-react` plugin and `@testing-library/react` for component testing
+- For Vue: use `@rsbuild/plugin-vue` plugin and `@testing-library/vue` for component testing
+- Create a `rstest.setup.ts` with `expect.extend(jestDomMatchers)` and `afterEach(() => cleanup())` for Testing Library
+- Add the setup file to `setupFiles` in config
+- For SSR testing, use `testEnvironment: 'node'` and test with `react-dom/server` or framework-specific SSR APIs
+
+## Mocking
+
+- Use `rs.mock('./module')` to mock modules
+- Use `rs.fn()` to create mock functions
+- Use `rs.spyOn(object, 'method')` to spy on methods
+- Prefer `clearMocks`, `resetMocks`, or `restoreMocks` config options to automatically clean up mocks between tests
+- Use factory functions in `rs.mock('./module', () => ({ ... }))` to provide mock implementations
+
+## Snapshot testing
+
+- Use `toMatchSnapshot()` for general snapshot testing
+- Use `toMatchInlineSnapshot()` for small, readable inline snapshots
+- Use `toMatchFileSnapshot()` for large or structured outputs (e.g., HTML, generated code)
+- Keep snapshots concise — only include relevant data, avoid timestamps and session IDs
+- Use `expect.addSnapshotSerializer()` to mask paths or sensitive data in snapshots
+- Use `path-serializer` to normalize file paths across platforms
+- Review snapshot changes carefully in code review
+
+## Coverage
+
+- Enable coverage with `--coverage` CLI flag or `coverage.enabled: true` in config
+- Install `@rstest/coverage-istanbul` for the Istanbul coverage provider
+- Use `coverage.include` to specify source files for coverage (e.g., `['src/**/*.{js,ts,tsx}']`)
+- Use `coverage.thresholds` to enforce minimum coverage requirements
+- Use `coverage.reporters` to generate reports in different formats (e.g., `text`, `lcov`, `html`)
+
+## Multi-project testing
+
+- Use `projects` field in root config to define multiple test projects
+- For monorepos, use glob patterns like `'packages/*'` to auto-discover sub-projects
+- Use `defineProject` helper in sub-project configs
+- Extract shared config and use `mergeRstestConfig` to compose project configs
+- Global options (`reporters`, `pool`, `isolate`, `coverage`, `bail`) must be set at the root level, not in projects
+
+## CI integration
+
+- Use `rstest run` (not `rstest watch`) in CI
+- Use `--shard` for parallel test execution across CI machines (e.g., `--shard 1/3`)
+- Use `--reporter=blob` with `rstest merge-reports` to combine sharded results
+- Use `--reporter=junit` with `outputPath` for CI report integration
+- The `github-actions` reporter is auto-enabled in GitHub Actions for inline error annotations
+- Use `--bail` to stop early on first failure when appropriate
+
+## Performance
+
+- Disable `isolate` (`--no-isolate`) when tests have no side effects for faster execution via module cache reuse
+- Use `pool.maxWorkers` to control parallelism based on available resources
+- Keep test build fast by avoiding unnecessary Rspack plugins in test config
+- Use test filtering (`rstest <pattern>` or `-t <name>`) to run only relevant tests during development
+- Leverage watch mode's incremental re-runs for fast local feedback
+
+## Debugging
+
+- Run with `DEBUG=rstest` to enable debug mode, which writes final configs and build outputs to disk
+- Read generated files in `dist/.rstest-temp/.rsbuild/` to confirm final Rstest/Rsbuild/Rspack config
+- Use VS Code's JavaScript Debug Terminal to run `rstest` with breakpoints
+- Use `--reporter=verbose` for detailed per-test output
+- Use `--printConsoleTrace` to trace console calls to their source
+- Add VS Code launch config for debugging specific test files with `@rstest/core/bin/rstest.js`
+
+## Profiling
+
+- Use Rsdoctor with `RSDOCTOR=true rstest run` to analyze test build performance
+- Use `samply` for native profiling of both main and worker processes
+- Use Node.js `--heap-prof` for memory profiling
+
+## Toolchain integration
+
+- Use the official VS Code extension (`rstack.rstest`) for in-editor test running and debugging
+- For Rslib libraries, use `@rstest/adapter-rslib` for config reuse
+- For Rsbuild apps, use `@rstest/adapter-rsbuild` for config reuse
+- Use `process.env.RSTEST` to detect test environment and apply test-specific config
+
+## Documentation
+
+- For the latest Rstest docs, read https://rstest.rs/llms.txt

package/template-workspace/.agents/skills-lock.json

@@ -0,0 +1,114 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "repository": "https://github.com/rstackjs/agent-skills",
+    "commit": "61c948b42512e223bad44b83af4080eba48b2677",
+    "license": "MIT",
+    "licensePath": ".agents/rstackjs-agent-skills-LICENSE"
+  },
+  "installDir": ".agents/skills",
+  "sources": [
+    {
+      "id": "rstack-agent-skills",
+      "visibility": "public",
+      "repository": "https://github.com/rstackjs/agent-skills",
+      "commit": "61c948b42512e223bad44b83af4080eba48b2677",
+      "license": "MIT",
+      "licensePath": ".agents/rstackjs-agent-skills-LICENSE",
+      "install": "vendored"
+    },
+    {
+      "id": "module-federation-agent-skills",
+      "visibility": "public",
+      "repository": "https://github.com/module-federation/agent-skills",
+      "commit": "07bb5b6c43ad457609e00c081b72d4c42508ec76",
+      "install": "clone",
+      "baseline": [
+        {
+          "name": "mf",
+          "path": ".agents/skills/mf",
+          "reason": "Module Federation docs, config inspection, type checking, shared dependency checks, and observability troubleshooting"
+        }
+      ]
+    },
+    {
+      "id": "techsiocz-private",
+      "visibility": "private",
+      "repository": "https://github.com/TechsioCZ/skills",
+      "install": "clone-if-authorized",
+      "baseline": [
+        {
+          "name": "plan-graph",
+          "reason": "Build and validate DAGs from .plan.md files"
+        },
+        {
+          "name": "dag",
+          "reason": "Inspect current plan frontiers and blocked lanes"
+        },
+        {
+          "name": "subagent-graph",
+          "reason": "Design dependency-aware multi-agent launch graphs"
+        },
+        {
+          "name": "helm",
+          "reason": "Steer already-running multi-agent work"
+        },
+        {
+          "name": "debugger-mode",
+          "reason": "Run hypothesis-driven debugging with runtime evidence"
+        }
+      ]
+    }
+  ],
+  "baseline": [
+    {
+      "name": "rsbuild-best-practices",
+      "path": ".agents/skills/rsbuild-best-practices",
+      "reason": "Modern.js application build configuration and Rsbuild troubleshooting"
+    },
+    {
+      "name": "rspack-best-practices",
+      "path": ".agents/skills/rspack-best-practices",
+      "reason": "Rspack bundling, CSS, asset, profiling, and production behavior"
+    },
+    {
+      "name": "rspack-tracing",
+      "path": ".agents/skills/rspack-tracing",
+      "reason": "Trace-backed Rspack failure and performance debugging"
+    },
+    {
+      "name": "rsdoctor-analysis",
+      "path": ".agents/skills/rsdoctor-analysis",
+      "reason": "Evidence-backed bundle composition, duplication, and retained-module analysis"
+    },
+    {
+      "name": "rslib-best-practices",
+      "path": ".agents/skills/rslib-best-practices",
+      "reason": "Rslib shared package and design-system library authoring"
+    },
+    {
+      "name": "rslib-modern-package",
+      "path": ".agents/skills/rslib-modern-package",
+      "reason": "Modern package contracts, exports, declarations, side effects, and release readiness"
+    },
+    {
+      "name": "rstest-best-practices",
+      "path": ".agents/skills/rstest-best-practices",
+      "reason": "Rstest configuration, test writing, mocking, snapshots, coverage, and CI behavior"
+    },
+    {
+      "name": "mf",
+      "path": ".agents/skills/mf",
+      "reason": "Module Federation docs, config inspection, type checking, shared dependency checks, and observability troubleshooting"
+    }
+  ],
+  "excludedByDefault": [
+    "migrate-to-rsbuild",
+    "migrate-to-rslib",
+    "migrate-to-rslint",
+    "migrate-to-rstest",
+    "rsbuild-v2-upgrade",
+    "rspack-v2-upgrade",
+    "rspress-v2-upgrade"
+  ]
+}

package/template-workspace/.codex/hooks.json

@@ -0,0 +1,16 @@
+{
+  "Stop": [
+    {
+      "command": "pnpm format && pnpm lint:fix && pnpm check",
+      "timeout": 600000,
+      "statusMessage": "Running UltraModern quality gates"
+    }
+  ],
+  "SubagentStop": [
+    {
+      "command": "pnpm format && pnpm lint:fix && pnpm check",
+      "timeout": 600000,
+      "statusMessage": "Running UltraModern quality gates"
+    }
+  ]
+}

package/template-workspace/.github/renovate.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": ["config:recommended", "helpers:pinGitHubActionDigests"],
+  "dependencyDashboard": true,
+  "minimumReleaseAge": "1 day",
+  "prConcurrentLimit": 5,
+  "prHourlyLimit": 2,
+  "rangeStrategy": "bump",
+  "schedule": ["before 5am on monday"],
+  "timezone": "Etc/UTC",
+  "packageRules": [
+    {
+      "matchManagers": ["github-actions"],
+      "groupName": "github-actions",
+      "labels": ["dependencies", "github-actions", "security"]
+    },
+    {
+      "matchManagers": ["npm"],
+      "matchUpdateTypes": ["patch", "minor"],
+      "groupName": "npm minor and patch updates",
+      "labels": ["dependencies", "npm"]
+    },
+    {
+      "matchUpdateTypes": ["major"],
+      "dependencyDashboardApproval": true,
+      "labels": ["dependencies", "major"]
+    }
+  ]
+}

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

@@ -0,0 +1,67 @@
+name: Ultramodern Workspace Gates
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+defaults:
+  run:
+    shell: bash
+
+concurrency:
+  group: ultramodern-workspace-gates-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  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
+        with:
+          egress-policy: audit
+
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 1
+          persist-credentials: false
+
+      - name: Setup Node.js
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: "{{nodeVersion}}"
+
+      - name: Setup mise
+        uses: jdx/mise-action@5ac50f778e26fac95da98d50503682459e86d566 # v3.2.0
+
+      - name: Install Dependencies
+        run: mise exec -- pnpm install --frozen-lockfile
+
+      - name: Run ${{ matrix.name }}
+        env:
+          MODERN_PUBLIC_SITE_URL: http://localhost:8080
+        run: mise exec -- ${{ matrix.command }}

package/template-workspace/.gitignore.handlebars

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+build/
+.modernjs/cache/
+.modernjs/agent-reference-repos-tmp/

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

@@ -0,0 +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

package/template-workspace/pnpm-workspace.yaml.handlebars

@@ -0,0 +1,45 @@
+packages:
+  - apps/*
+  - verticals/*
+  - packages/*
+
+minimumReleaseAge: 1440
+minimumReleaseAgeStrict: true
+minimumReleaseAgeIgnoreMissingTime: false
+minimumReleaseAgeExclude:
+  - '@bleedingdev/modern-js-*'
+  - '@tanstack/react-router'
+  - '@tanstack/router-core'
+  - 'typescript'
+  - '@typescript/native-preview'
+  - '@typescript/native-preview-*'
+  - '@types/react'
+trustPolicy: no-downgrade
+trustPolicyIgnoreAfter: 1440
+blockExoticSubdeps: true
+engineStrict: true
+pmOnFail: error
+verifyDepsBeforeRun: error
+strictDepBuilds: true
+
+peerDependencyRules:
+  allowedVersions:
+    react: '>=19.0.0'
+    '@module-federation/dts-plugin>typescript': '{{typescriptVersion}}'
+    '@module-federation/enhanced>typescript': '{{typescriptVersion}}'
+    '@module-federation/modern-js-v3>typescript': '{{typescriptVersion}}'
+    '@module-federation/rspack>typescript': '{{typescriptVersion}}'
+    'i18next>typescript': '{{typescriptVersion}}'
+
+overrides:
+  '@tanstack/react-router': {{tanstackRouterVersion}}
+  node-fetch: '{{nodeFetchVersion}}'
+
+allowBuilds:
+  '@swc/core': true
+  core-js: true
+  esbuild: true
+  lefthook: true
+  msgpackr-extract: true
+  sharp: true
+  workerd: true