@bleedingdev/modern-js-create 3.2.0-ultramodern.10 → 3.2.0-ultramodern.100

package/template/src/routes/[lang]/page.tsx.handlebars

@@ -0,0 +1,211 @@
+import { Helmet } from '@modern-js/runtime/head';
+import { useModernI18n } from '@modern-js/plugin-i18n/runtime';
+import { useLocation } from '{{routerRuntimeImport}}';
+{{#if useEffectBff}}import effectBff from '@api/effect/index';
+import { Effect } from '@modern-js/plugin-bff/effect-client';
+import { useEffect, useState } from 'react';
+{{/if}}
+import { useTranslation } from 'react-i18next';
+
+{{#if useEffectBff}}type GreetingResponse = Awaited<ReturnType<typeof effectBff.client.greetings.hello>>;
+
+{{/if}}
+const fallbackLanguage = 'en';
+const supportedLanguages = ['en', 'cs'] as const;
+type SupportedLanguage = (typeof supportedLanguages)[number];
+
+const isSupportedLanguage = (value: string): value is SupportedLanguage =>
+  supportedLanguages.includes(value as SupportedLanguage);
+
+const stripLanguagePrefix = (pathname: string) => {
+  const segments = pathname.split('/').filter(Boolean);
+  if (segments.length > 0 && isSupportedLanguage(segments[0] ?? '')) {
+    segments.shift();
+  }
+  return `/${segments.join('/')}`;
+};
+
+const localizedPath = (pathname: string, language: SupportedLanguage) => {
+  const pathWithoutLanguage = stripLanguagePrefix(pathname);
+  return pathWithoutLanguage === '/' ? `/${language}` : `/${language}${pathWithoutLanguage}`;
+};
+
+const absoluteUrl = (pathname: string) => {
+  const origin = ULTRAMODERN_SITE_URL.replace(/\/+$/u, '');
+  return `${origin}${pathname}`;
+};
+
+const locationSuffix = (location: { hash?: unknown; search?: unknown; searchStr?: unknown }) => {
+  const { hash, search, searchStr } = location;
+  let locationSearch = '';
+  if (typeof searchStr === 'string') {
+    locationSearch = searchStr;
+  } else if (typeof search === 'string') {
+    locationSearch = search;
+  }
+  const locationHash = typeof hash === 'string' ? hash : '';
+  return `${locationSearch}${locationHash}`;
+};
+
+const Index = () => {
+  const { t } = useTranslation();
+  const { language } = useModernI18n();
+  const location = useLocation();
+  const currentLanguage = isSupportedLanguage(language) ? language : fallbackLanguage;
+  const canonicalPath = localizedPath(location.pathname, currentLanguage);
+  const suffix = locationSuffix(location);
+  const languageOptions = supportedLanguages.map((code) => ({
+    code,
+    href: `${localizedPath(location.pathname, code)}${suffix}`,
+    label: t(`home.language.${code}`),
+  }));
+{{#if useEffectBff}}  const [effectMessage, setEffectMessage] = useState('loading...');
+
+  useEffect(() => {
+    let mounted = true;
+    Effect.runFork(
+      Effect.promise(() => effectBff.client.greetings.hello({})).pipe(
+        Effect.tap((data: GreetingResponse) =>
+          Effect.sync(() => {
+            if (mounted) {
+              setEffectMessage(data.message);
+            }
+          }),
+        ),
+      ),
+    );
+    return () => {
+      mounted = false;
+    };
+  }, []);
+{{/if}}
+  return (
+    <div className="container-box">
+      <Helmet>
+        <link
+          rel="icon"
+          type="image/x-icon"
+          href="https://lf3-static.bytednsdoc.com/obj/eden-cn/uhbfnupenuhf/favicon.ico"
+        />
+        <link rel="canonical" href={absoluteUrl(canonicalPath)} />
+        {supportedLanguages.map((code) => (
+          <link
+            href={absoluteUrl(localizedPath(location.pathname, code))}
+            hrefLang={code}
+            key={code}
+            rel="alternate"
+          />
+        ))}
+        <link
+          href={absoluteUrl(localizedPath(location.pathname, fallbackLanguage))}
+          hrefLang="x-default"
+          rel="alternate"
+        />
+      </Helmet>
+      <main>
+        <nav className="language-switcher" aria-label={t('home.language.switcher')}>
+          {languageOptions.map((option) => (
+            <a
+              aria-current={currentLanguage === option.code ? 'page' : undefined}
+              href={option.href}
+              key={option.code}
+            >
+              {option.label}
+            </a>
+          ))}
+        </nav>
+        <div className="title">
+          {t('home.title')}
+          <img
+            alt={t('home.logoAlt')}
+            className="logo"
+            src="https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/modern-js-logo.svg"
+          />
+          <p className="name">{t('home.name')}</p>
+        </div>
+        <p className="description{{#if enableTailwind}} text-emerald-700 font-semibold{{/if}}">
+          {t('home.description.intro')}{' '}
+          <code className="code">presetUltramodern(...)</code>{' '}
+          {t('home.description.afterPreset')}{' '}
+          <code className="code">modern.config.ts</code>{' '}
+          {t('home.description.afterConfig')}{' '}
+          <code className="code">pnpm run ultramodern:check</code>{' '}
+          {t('home.description.end')}
+        </p>
+{{#if useEffectBff}}
+        <p className="description effect-message{{#if enableTailwind}} text-emerald-700 font-semibold{{/if}}">
+          {t('home.bff.response')} <code className="code">{effectMessage}</code>
+        </p>
+{{/if}}
+        <div className="grid">
+          <a
+            href="https://bleedingdev.github.io/ultramodern.js/guides/get-started/ultramodern.html"
+            target="_blank"
+            rel="noopener noreferrer"
+            className="card"
+          >
+            <h2>
+              {t('home.cards.guide.title')}
+              <img
+                alt=""
+                className="arrow-right"
+                src="https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/arrow-right.svg"
+              />
+            </h2>
+            <p>{t('home.cards.guide.body')}</p>
+          </a>
+          <a
+            href="https://bleedingdev.github.io/ultramodern.js/configure/app/usage.html"
+            target="_blank"
+            className="card"
+            rel="noreferrer"
+          >
+            <h2>
+              {t('home.cards.config.title')}
+              <img
+                alt=""
+                className="arrow-right"
+                src="https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/arrow-right.svg"
+              />
+            </h2>
+            <p>{t('home.cards.config.body')}</p>
+          </a>
+          <a
+            href="https://github.com/BleedingDev/ultramodern.js/blob/main-ultramodern/packages/toolkit/create/template/.github/workflows/ultramodern-gates.yml.handlebars"
+            target="_blank"
+            className="card"
+            rel="noreferrer"
+          >
+            <h2>
+              {t('home.cards.gates.title')}
+              <img
+                alt=""
+                className="arrow-right"
+                src="https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/arrow-right.svg"
+              />
+            </h2>
+            <p>{t('home.cards.gates.body')}</p>
+          </a>
+          <a
+            href="https://bleedingdev.github.io/ultramodern.js/configure/app/bff/effect.html"
+            target="_blank"
+            rel="noopener noreferrer"
+            className="card"
+          >
+            <h2>
+              {t('home.cards.bff.title')}
+              <img
+                alt=""
+                className="arrow-right"
+                src="https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/arrow-right.svg"
+              />
+            </h2>
+            <p>{t('home.cards.bff.body')}</p>
+          </a>
+        </div>
+      </main>
+    </div>
+  );
+};
+
+export default Index;

package/template/src/routes/layout.tsx.handlebars

@@ -1,4 +1,5 @@
-import { Outlet } from '@modern-js/runtime/{{routerImportPath}}';
+import { Outlet } from '{{routerRuntimeImport}}';
+import './index.css';
 
 export default function Layout() {
   return (

package/template/tailwind.config.ts.handlebars

@@ -2,9 +2,9 @@
 
 export default {
   content: ['./src/**/*.{js,ts,jsx,tsx}'],
+  plugins: [],
   theme: {
     extend: {},
   },
-  plugins: [],
 } satisfies Config;
 {{/if}}

package/template/tests/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "types": ["@rstest/core/globals"]
+  },
+  "include": ["./"]
+}

package/template/tests/ultramodern.contract.test.ts.handlebars

@@ -0,0 +1,78 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { describe, expect, test } from '@rstest/core';
+
+const root = process.cwd();
+const readText = (relativePath: string) =>
+  fs.readFileSync(path.join(root, relativePath), 'utf-8');
+const readJson = <T>(relativePath: string): T =>
+  JSON.parse(readText(relativePath)) as T;
+
+describe('generated UltraModern contract', () => {
+  test('keeps localized route metadata and Rstest wiring', () => {
+    expect(fs.existsSync(path.join(root, 'src/routes/[lang]/page.tsx'))).toBe(
+      true,
+    );
+    expect(fs.existsSync(path.join(root, 'src/routes/page.tsx'))).toBe(false);
+    expect(fs.existsSync(path.join(root, 'src/routes/layout.tsx'))).toBe(true);
+{{#if enableTailwind}}
+    expect(fs.existsSync(path.join(root, 'postcss.config.mjs'))).toBe(true);
+    expect(fs.existsSync(path.join(root, 'tailwind.config.ts'))).toBe(true);
+{{/if}}
+{{#unless enableTailwind}}
+    expect(fs.existsSync(path.join(root, 'postcss.config.mjs'))).toBe(false);
+    expect(fs.existsSync(path.join(root, 'tailwind.config.ts'))).toBe(false);
+{{/unless}}
+  });
+
+  test('retains package-source metadata for generated Modern.js packages', () => {
+    const packageJson = readJson<{
+      dependencies?: Record<string, string>;
+      devDependencies?: Record<string, string>;
+      modernjs?: {
+        packageSource?: {
+          config?: string;
+        };
+        preset?: string;
+      };
+    }>('package.json');
+    const packageSource = readJson<{
+      modernPackages?: {
+        packages?: string[];
+        specifier?: string;
+      };
+      strategy?: string;
+    }>('.modernjs/ultramodern-package-source.json');
+
+    expect(packageJson.modernjs?.preset).toBe('presetUltramodern');
+    expect(packageJson.modernjs?.packageSource?.config).toBe(
+      './.modernjs/ultramodern-package-source.json',
+    );
+    expect(packageSource.strategy).toMatch(/^(workspace|install)$/u);
+    expect(packageSource.modernPackages?.packages).toContain(
+      '@modern-js/runtime',
+    );
+    expect(packageSource.modernPackages?.packages).toContain(
+      '@modern-js/app-tools',
+    );
+    expect(packageSource.modernPackages?.packages).toContain(
+      '@modern-js/adapter-rstest',
+    );
+    expect(packageSource.modernPackages?.specifier).toBeTruthy();
+    expect(
+      packageJson.devDependencies?.['@modern-js/adapter-rstest'],
+    ).toBeTruthy();
+{{#if enableTailwind}}
+    expect(packageJson.devDependencies?.tailwindcss).toBe('^4.3.0');
+    expect(packageJson.devDependencies?.['@tailwindcss/postcss']).toBe(
+      '^4.3.0',
+    );
+{{/if}}
+{{#unless enableTailwind}}
+    expect(packageJson.devDependencies?.tailwindcss).toBeUndefined();
+    expect(
+      packageJson.devDependencies?.['@tailwindcss/postcss'],
+    ).toBeUndefined();
+{{/unless}}
+  });
+});

package/template/tsconfig.json

@@ -12,6 +12,7 @@
     "verbatimModuleSyntax": true,
     "noEmit": true,
     "allowJs": true,
+    "allowImportingTsExtensions": true,
     "resolveJsonModule": true,
     "esModuleInterop": true,
     "skipLibCheck": true,

package/template-workspace/.agents/agent-reference-repos.json

@@ -0,0 +1,24 @@
+{
+  "schemaVersion": 1,
+  "defaultEnabled": true,
+  "strategy": "git-subtree-squash",
+  "installDir": "repos",
+  "repositories": [
+    {
+      "id": "effect",
+      "name": "Effect",
+      "url": "https://github.com/Effect-TS/effect.git",
+      "ref": "main",
+      "path": "repos/effect",
+      "readOnly": true
+    },
+    {
+      "id": "ultramodern-js",
+      "name": "UltraModern.js",
+      "url": "https://github.com/BleedingDev/ultramodern.js.git",
+      "ref": "main-ultramodern",
+      "path": "repos/ultramodern.js",
+      "readOnly": true
+    }
+  ]
+}

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

@@ -17,6 +17,20 @@
       "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",
@@ -81,6 +95,11 @@
       "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": [

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

@@ -1,6 +1,8 @@
 # UltraModern Agent Contract
 
-This workspace is generated as an agent-ready UltraModern.js SuperApp. Agents should treat the files under `.agents/skills` as local project instructions, not optional reading.
+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
 
@@ -8,6 +10,19 @@ This workspace is generated as an agent-ready UltraModern.js SuperApp. Agents sh
 - `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` 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`.
+
+## 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
 
@@ -20,6 +35,9 @@ Use these skills when the task touches the matching subsystem:
 - `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
 
@@ -29,17 +47,30 @@ ScriptedAlchemy/TechsioCZ skills are private and are cloned only when the curren
 pnpm skills:install
 ```
 
-The installer copies only the allowlisted private skills from `.agents/skills-lock.json`: `plan-graph`, `dag`, `subagent-graph`, `helm`, and `debugger-mode`.
+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.
-- Prefer Effect for BFF/service code.
+- 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 design-system code as a normal Micro Frontend or shared package, not a special core path.
+- 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 and private TechsioCZ skill allowlist 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 `pnpm check`.

package/template-workspace/README.md.handlebars

@@ -3,23 +3,48 @@
 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 ultramodern:check
+pnpm dlx @bleedingdev/modern-js-create transportation --vertical
+pnpm dlx @bleedingdev/modern-js-create payments --vertical
 ```
 
-The topology and ownership metadata are generated under `topology/`.
+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 install
+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 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
@@ -27,3 +52,28 @@ UltraModern.js runtime and tooling packages on `workspace:*` for monorepo
 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.
+
+## 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.
+
+```bash
+pnpm cloudflare:deploy
+ULTRAMODERN_PUBLIC_URL_SHELL_SUPER_APP=https://shell-super-app.example.workers.dev \
+pnpm cloudflare:proof -- --require-public-urls
+```
+
+## Troubleshooting
+
+| Symptom | Current check | Owner |
+| --- | --- | --- |
+| 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 |
+| 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 |
+| Federation manifest failure | Run the shell and vertical build scripts, then check each deployed `/mf-manifest.json` URL used by the shell. | Module Federation owner |