@bleedingdev/modern-js-create 3.2.0-ultramodern.6 → 3.2.0-ultramodern.61

package/template-workspace/.agents/skills/rspack-tracing/scripts/analyze_trace.js

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+// Parse duration string (e.g., "1.23ms", "456.78µs", "0.12s") to milliseconds
+function parseDuration(durationStr) {
+  if (!durationStr) return 0;
+
+  const match = durationStr.match(/^([\d.]+)(ms|µs|s|ns)$/);
+  if (!match) return 0;
+
+  const value = parseFloat(match[1]);
+  const unit = match[2];
+
+  switch (unit) {
+    case 's':
+      return value * 1000;
+    case 'ms':
+      return value;
+    case 'µs':
+      return value / 1000;
+    case 'ns':
+      return value / 1000000;
+    default:
+      return value;
+  }
+}
+
+// Get trace file path
+const tracePath = process.argv[2] || path.join(__dirname, 'trace.json');
+
+if (!fs.existsSync(tracePath)) {
+  console.error(`Error: Trace file not found at ${tracePath}`);
+  console.error('Usage: node analyze_trace.js <path-to-trace.json>');
+  process.exit(1);
+}
+
+console.log(`Analyzing trace file: ${tracePath}\n`);
+
+try {
+  const fileContent = fs.readFileSync(tracePath, 'utf8');
+
+  // Parse line-delimited JSON
+  const events = fileContent
+    .trim()
+    .split('\n')
+    .map(line => {
+      try {
+        return JSON.parse(line);
+      } catch (err) {
+        return null;
+      }
+    })
+    .filter(Boolean);
+
+  if (!events.length) {
+    console.error('No valid trace events found.');
+    process.exit(1);
+  }
+
+  console.log('=== Rspack Build Performance Analysis ===\n');
+  console.log(`Total events: ${events.length}\n`);
+
+  // Categorize events by target
+  const pluginStats = new Map();
+  const loaderStats = new Map();
+
+  events.forEach(event => {
+    const target = event.target;
+    const timeField = event.fields?.['time.busy'];
+
+    if (!timeField) return;
+
+    const duration = parseDuration(timeField);
+
+    if (target === 'Plugin Analysis') {
+      // Plugin performance
+      const pluginName = event.span?.name;
+      if (!pluginName) return;
+
+      if (!pluginStats.has(pluginName)) {
+        pluginStats.set(pluginName, {
+          count: 0,
+          total: 0,
+          max: 0,
+          min: Infinity,
+        });
+      }
+
+      const stat = pluginStats.get(pluginName);
+      stat.count++;
+      stat.total += duration;
+      stat.max = Math.max(stat.max, duration);
+      stat.min = Math.min(stat.min, duration);
+    } else if (target === 'Loader Analysis') {
+      // Loader performance
+      let loaderName = event.span?.name;
+
+      // For pitch phase (span.name is null), use resource path
+      if (!loaderName) {
+        const resource = event.fields?.resource;
+        if (resource) {
+          // Extract filename from resource path
+          const cleanResource = resource.replace(/^"|"$/g, ''); // Remove quotes
+          const filename = cleanResource.split('/').pop();
+          loaderName = `Loader pitch for ${filename}`;
+        } else {
+          loaderName = 'Loader pitch (unknown resource)';
+        }
+      }
+
+      if (!loaderStats.has(loaderName)) {
+        loaderStats.set(loaderName, {
+          count: 0,
+          total: 0,
+          max: 0,
+          min: Infinity,
+        });
+      }
+
+      const stat = loaderStats.get(loaderName);
+      stat.count++;
+      stat.total += duration;
+      stat.max = Math.max(stat.max, duration);
+      stat.min = Math.min(stat.min, duration);
+    }
+  });
+
+  // Display Plugin Analysis
+  if (pluginStats.size > 0) {
+    console.log('🔌 Plugin Analysis (by name):');
+    console.log('─'.repeat(80));
+
+    const sortedPlugins = [...pluginStats.entries()].sort(
+      (a, b) => b[1].total - a[1].total,
+    );
+
+    sortedPlugins.forEach(([name, stat]) => {
+      const avg = stat.total / stat.count;
+      console.log(`${name}`);
+      console.log(
+        `  Total: ${stat.total.toFixed(2)}ms | Count: ${stat.count} | ` +
+          `Avg: ${avg.toFixed(2)}ms | Max: ${stat.max.toFixed(2)}ms | Min: ${stat.min.toFixed(2)}ms`,
+      );
+      console.log('');
+    });
+
+    const totalPluginTime = [...pluginStats.values()].reduce(
+      (sum, stat) => sum + stat.total,
+      0,
+    );
+    console.log(`Total Plugin Time: ${totalPluginTime.toFixed(2)}ms\n`);
+  }
+
+  // Display Loader Analysis
+  if (loaderStats.size > 0) {
+    console.log('\n🔧 Loader Analysis (by name):');
+    console.log('─'.repeat(80));
+
+    const sortedLoaders = [...loaderStats.entries()].sort(
+      (a, b) => b[1].total - a[1].total,
+    );
+
+    sortedLoaders.forEach(([name, stat]) => {
+      const avg = stat.total / stat.count;
+      console.log(`${name}`);
+      console.log(
+        `  Total: ${stat.total.toFixed(2)}ms | Count: ${stat.count} | ` +
+          `Avg: ${avg.toFixed(2)}ms | Max: ${stat.max.toFixed(2)}ms | Min: ${stat.min.toFixed(2)}ms`,
+      );
+      console.log('');
+    });
+
+    const totalLoaderTime = [...loaderStats.values()].reduce(
+      (sum, stat) => sum + stat.total,
+      0,
+    );
+    console.log(`Total Loader Time: ${totalLoaderTime.toFixed(2)}ms\n`);
+  }
+} catch (err) {
+  console.error('Error processing trace file:', err);
+  process.exit(1);
+}

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,54 @@
+name: Ultramodern Workspace Gates
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+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:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    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: 24
+
+      - name: Setup mise
+        uses: jdx/mise-action@5ac50f778e26fac95da98d50503682459e86d566 # v3.2.0
+
+      - 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
+        env:
+          MODERN_PUBLIC_SITE_URL: http://localhost:8080
+        run: mise exec -- pnpm build

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,2 @@
+[tools]
+pnpm = "{{pnpmVersion}}"

package/template-workspace/AGENTS.md

@@ -0,0 +1,76 @@
+# UltraModern Agent Contract
+
+This workspace is generated as an agent-ready UltraModern.js SuperApp shell.
+Agents should treat the files under `.agents/skills` as local project
+instructions, not optional reading.
+
+## Quality Gates
+
+- `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.
+- Generated Codex stop hooks and subagent-stop hooks run `pnpm format && pnpm lint:fix && pnpm check`.
+- `postinstall` installs `lefthook` when the workspace is inside a Git worktree. Generated `lefthook.yml` runs `pnpm format`, `pnpm lint:fix`, and `pnpm check` on pre-commit; pre-push runs `pnpm check`.
+
+## Localized Routes
+
+Generated apps keep locale-prefixed entry routes under `src/routes/[lang]`,
+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.
+
+## Required Skill Baseline
+
+Use these skills when the task touches the matching subsystem:
+
+- `rsbuild-best-practices`: Modern.js app build configuration, Rsbuild options, assets, type checking, and build debugging.
+- `rspack-best-practices`: Rspack-level bundling, CSS, assets, profiling, and production build behavior.
+- `rspack-tracing`: Rspack build failures, slow builds, crash localization, and trace analysis.
+- `rsdoctor-analysis`: Evidence-based bundle analysis from `rsdoctor-data.json`, including duplicate packages, large chunks, and retained modules.
+- `rslib-best-practices`: Shared packages, generated libraries, declaration output, and Rslib configuration.
+- `rslib-modern-package`: Package contracts for shared libraries, exports, side effects, dependency placement, README, and release readiness.
+- `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.
+
+## Private Skills
+
+ScriptedAlchemy/TechsioCZ skills are private and are cloned only when the current developer is authorized for `TechsioCZ/skills`.
+
+```bash
+pnpm skills:install
+```
+
+The installer copies only the pinned private skills from `.agents/skills-lock.json`: `plan-graph`, `dag`, `subagent-graph`, `helm`, and `debugger-mode`.
+
+## 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:
+
+- `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`.
+
+## Project Priorities
+
+- Keep `presetUltramodern` as the single preset.
+- Keep the initial workspace shell-only unless a user explicitly asks for a
+  starter vertical.
+- Use `create <domain> --vertical` as the growth path for real business
+  MicroVerticals.
+- Prefer Effect for BFF code.
+- Prefer TanStack Router for app routing.
+- Keep UI-kit or design-system code as ordinary vertical or shared package code, not a special core path.
+- Keep generated packages explicit and publishable: stable `exports`, correct declarations, small public APIs, and clear ownership metadata.
+- Do not add migration tooling or codemods unless the project owner explicitly asks for migration work.
+
+## 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`.

package/template-workspace/README.md.handlebars

@@ -3,23 +3,46 @@
 Generated UltraModern SuperApp workspace.
 
 This workspace keeps `presetUltramodern(...)` as the single public
-UltraModern.js 3.0 SuperApp surface and scaffolds the canonical Micro Vertical
-starter topology:
+UltraModern.js 3.0 SuperApp surface and starts with an explicit shell:
 
-- `apps/shell-super-app` owns shell route assembly and remote manifest wiring.
-- `apps/remotes/remote-commerce` owns the commerce vertical remote.
-- `apps/remotes/remote-identity` owns the identity vertical remote.
-- `apps/remotes/remote-design-system` owns the horizontal design-system remote.
-- `services/service-recommendations-effect` owns the Effect BFF service.
-- `packages/shared-*` provide placeholders for cross-workspace contracts.
+- `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.
+- `verticals/*` is intentionally empty until a real business domain is added.
 
-Run the scaffold validator before adding business code:
+Add a full-stack MicroVertical when the product needs one:
 
 ```bash
+pnpm create modern@latest transportation --vertical
+pnpm create modern@latest 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.
+
+Run the scaffold validator before adding business code and after every
+`--vertical` mutation:
+
+```bash
+mise install
 pnpm ultramodern:check
 ```
 
-The topology and ownership metadata are generated under `topology/`.
+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 topology and ownership metadata are generated under `topology/`. The
+workspace also ships `.github/workflows/ultramodern-workspace-gates.yml` and
+`.github/renovate.json` with read-only workflow permissions, commit-pinned
+actions, frozen installs, StepSecurity audit-mode runner hardening, dependency
+dashboard review, one-day release age, grouped updates, and manual approval for
+major upgrades.
 
 Package source metadata is generated at
 `.modernjs/ultramodern-package-source.json`. The default strategy keeps