mfeflow 0.1.0 → 0.3.0

package/assets/features/tailwind/files/shell-styles.css.eta

@@ -0,0 +1,22 @@
+<%_ const prefix = it.app.tailwindPrefix _%>
+/* The shell is the only app that loads Tailwind's reset (preflight). */
+@layer theme, base, components, utilities;
+@import 'tailwindcss/theme.css' layer(theme) prefix(<%= prefix %>);
+@import 'tailwindcss/preflight.css' layer(base);
+@import 'tailwindcss/utilities.css' layer(utilities) prefix(<%= prefix %>);
+
+/* Tokens read the theme variables (--mf-*). The second value is used when there is no theme. */
+@theme inline {
+  --color-background: var(--mf-color-bg, #ffffff);
+  --color-foreground: var(--mf-color-fg, #111827);
+  --color-surface: var(--mf-color-surface, #f3f4f6);
+  --color-primary: var(--mf-color-primary, #2563eb);
+  --color-primary-foreground: var(--mf-color-primary-fg, #ffffff);
+  --color-secondary: var(--mf-color-surface, #f3f4f6);
+  --color-secondary-foreground: var(--mf-color-fg, #111827);
+  --color-accent: var(--mf-color-surface, #f3f4f6);
+  --color-accent-foreground: var(--mf-color-fg, #111827);
+  --color-destructive: #dc2626;
+  --color-border: var(--mf-color-border, #e5e7eb);
+  --color-ring: var(--mf-color-primary, #2563eb);
+}

package/assets/features/testing/files/vitest.config.ts

@@ -1,8 +1,17 @@
 import { defineConfig } from 'vitest/config';
 
 export default defineConfig({
-  // One copy of React and Testing Library, also when a package like @mfeflow/testing is linked from another folder.
-  resolve: { dedupe: ['react', 'react-dom', '@testing-library/react', '@testing-library/dom'] },
+  // One copy of React, i18next and Testing Library, also when a package like @mfeflow/testing is linked from another folder.
+  resolve: {
+    dedupe: [
+      'react',
+      'react-dom',
+      'react-i18next',
+      'i18next',
+      '@testing-library/react',
+      '@testing-library/dom',
+    ],
+  },
   test: {
     environment: 'jsdom',
     include: ['src/**/*.test.{ts,tsx}'],

package/assets/features/theming/feature.json

@@ -0,0 +1,103 @@
+{
+  "name": "theming",
+  "version": "0.1.0",
+  "description": "Light and dark themes as CSS variables (@mfeflow/theme): the shell owns the provider and the persisted choice, every remote reads the same --mf-* tokens with no theme code of its own. The stored theme is set by an inline script in the shell's <head>, before any bundle loads, so a reload never paints the wrong colours.",
+  "requires": ["core", "tsconfig"],
+  "files": [
+    {
+      "to": "src/theme/themes.ts",
+      "target": "shell",
+      "from": "files/themes.ts"
+    },
+    {
+      "to": "src/theme/Theme.tsx",
+      "target": "shell",
+      "from": "files/Theme.tsx"
+    },
+    {
+      "to": "src/theme/ThemeToggle.tsx",
+      "target": "shell",
+      "from": "files/ThemeToggle.tsx"
+    },
+    {
+      "to": "src/theme/theme.css",
+      "target": "shell",
+      "from": "files/theme.css"
+    },
+    {
+      "to": "src/theme/apply-stored.ts",
+      "target": "shell",
+      "from": "files/apply-stored.ts"
+    },
+    {
+      "to": "src/theme/head-script.ts",
+      "target": "shell",
+      "from": "files/head-script.ts"
+    },
+    {
+      "to": "src/theme/apply-stored.test.ts",
+      "target": "shell",
+      "from": "files/apply-stored-test.ts",
+      "when": {
+        "feature:testing": true
+      }
+    },
+    {
+      "to": "src/theme/ThemeToggle.test.tsx",
+      "target": "shell",
+      "from": "files/theme-toggle-test.tsx",
+      "when": {
+        "feature:testing": true
+      }
+    },
+    {
+      "to": "src/theme/tokens.ts",
+      "target": "remotes",
+      "from": "files/tokens.ts"
+    },
+    {
+      "to": "src/theme/tokens.test.ts",
+      "target": "remotes",
+      "from": "files/tokens-test.ts",
+      "when": {
+        "feature:testing": true
+      }
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "@mfeflow/theme",
+      "range": "latest",
+      "target": "shell"
+    },
+    {
+      "name": "@mfeflow/theme",
+      "range": "latest",
+      "target": "remotes"
+    }
+  ],
+  "transforms": [
+    {
+      "op": "add-import",
+      "file": "rsbuild.config.ts",
+      "target": "shell",
+      "from": "./src/theme/head-script"
+    },
+    {
+      "op": "add-boot-step",
+      "file": "src/bootstrap.tsx",
+      "target": "shell",
+      "call": "applyStoredTheme",
+      "from": "./theme/apply-stored",
+      "await": false
+    },
+    {
+      "op": "wrap-provider",
+      "file": "src/App.tsx",
+      "target": "shell",
+      "component": "Theme",
+      "from": "./theme/Theme",
+      "function": "App"
+    }
+  ]
+}

package/assets/features/theming/files/Theme.tsx

@@ -0,0 +1,15 @@
+import type { ReactNode } from 'react';
+import { ThemeProvider } from '@mfeflow/theme/react';
+import { ThemeToggle } from './ThemeToggle';
+import { defaultTheme, followSystem, themes } from './themes';
+import './theme.css';
+
+/** Wraps the shell. The choice is stored under the shell's storage, so every tab and reload agrees. */
+export function Theme({ children }: { children: ReactNode }) {
+  return (
+    <ThemeProvider themes={themes} defaultTheme={defaultTheme} followSystem={followSystem}>
+      {children}
+      <ThemeToggle />
+    </ThemeProvider>
+  );
+}

package/assets/features/theming/files/ThemeToggle.tsx

@@ -0,0 +1,23 @@
+import { useTheme } from '@mfeflow/theme/react';
+
+/** Your component: move it into the header, restyle it, or swap it for a menu. */
+export function ThemeToggle() {
+  const { theme, themes, setTheme } = useTheme();
+  return (
+    <label className="theme-toggle">
+      Theme{' '}
+      <select
+        value={theme.name}
+        onChange={(event) => {
+          setTheme(event.target.value);
+        }}
+      >
+        {themes.map((name) => (
+          <option key={name} value={name}>
+            {name}
+          </option>
+        ))}
+      </select>
+    </label>
+  );
+}

package/assets/features/theming/files/apply-stored-test.ts

@@ -0,0 +1,37 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { applyStoredTheme, currentStartingTheme } from './apply-stored';
+
+afterEach(() => {
+  localStorage.clear();
+  document.documentElement.removeAttribute('data-theme');
+});
+
+describe('applyStoredTheme', () => {
+  it('uses the default theme when nothing is stored', () => {
+    expect(currentStartingTheme().name).toBe('light');
+  });
+
+  it('puts the stored theme on <html> with its variables', () => {
+    localStorage.setItem('shell:theme', JSON.stringify('dark'));
+    applyStoredTheme();
+    expect(document.documentElement.dataset.theme).toBe('dark');
+    expect(document.documentElement.style.getPropertyValue('--mf-color-bg')).not.toBe('');
+  });
+
+  it('ignores a stored value that is not a theme', () => {
+    localStorage.setItem('shell:theme', '{broken');
+    expect(currentStartingTheme().name).toBe('light');
+    localStorage.setItem('shell:theme', JSON.stringify('purple'));
+    expect(currentStartingTheme().name).toBe('light');
+  });
+
+  it.each(['constructor', '__proto__', 'toString'])(
+    'ignores a stored name that only exists on every object: %s',
+    (name) => {
+      localStorage.setItem('shell:theme', JSON.stringify(name));
+      expect(currentStartingTheme().name).toBe('light');
+      applyStoredTheme();
+      expect(document.documentElement.dataset.theme).toBe('light');
+    },
+  );
+});

package/assets/features/theming/files/apply-stored.ts

@@ -0,0 +1,13 @@
+import { applyTheme, type Theme } from '@mfeflow/theme';
+import { startingTheme } from '@mfeflow/theme/starting';
+import { defaultTheme, followSystem, themes } from './themes';
+
+/** The theme to show before React renders: the stored choice, else the system preference (if followSystem), else the default. */
+export function currentStartingTheme(): Theme {
+  return startingTheme(themes, { defaultTheme, followSystem });
+}
+
+/** The first boot step: the variables are on <html> before the first render, also when the head script was blocked. */
+export function applyStoredTheme(): void {
+  applyTheme(currentStartingTheme());
+}

package/assets/features/theming/files/head-script.ts

@@ -0,0 +1,8 @@
+import { registerHeadScript } from '@mfeflow/rsbuild';
+import { noFlashScript } from '@mfeflow/theme';
+import { defaultTheme, followSystem, themes } from './themes';
+
+// Imported by rsbuild.config.ts. The script goes first in the shell's <head>, so the stored theme is on <html>
+// before any bundle has loaded. It needs the CSP to allow an inline script (a nonce or 'unsafe-inline');
+// without that, apply-stored.ts still sets the theme before the first render.
+registerHeadScript('theme', noFlashScript(themes, { defaultTheme, followSystem }));

package/assets/features/theming/files/theme-toggle-test.tsx

@@ -0,0 +1,18 @@
+import { fireEvent, screen } from '@testing-library/react';
+import { renderWithPlatform } from '@mfeflow/testing';
+import { describe, expect, it } from 'vitest';
+import { Theme } from './Theme';
+
+describe('Theme', () => {
+  it('switches the theme on <html> and remembers it', () => {
+    renderWithPlatform(
+      <Theme>
+        <p>content</p>
+      </Theme>,
+    );
+    expect(document.documentElement.dataset.theme).toBe('light');
+    fireEvent.change(screen.getByRole('combobox'), { target: { value: 'dark' } });
+    expect(document.documentElement.dataset.theme).toBe('dark');
+    expect(localStorage.getItem('shell:theme')).toBe('"dark"');
+  });
+});

package/assets/features/theming/files/theme.css

@@ -0,0 +1,14 @@
+html {
+  background: var(--mf-color-bg, #ffffff);
+  color: var(--mf-color-fg, #111827);
+}
+
+.theme-toggle {
+  position: fixed;
+  right: 1rem;
+  bottom: 1rem;
+  padding: 0.25rem 0.5rem;
+  border-radius: 0.5rem;
+  background: var(--mf-color-surface, #f3f4f6);
+  color: var(--mf-color-fg, #111827);
+}

package/assets/features/theming/files/themes.ts

@@ -0,0 +1,30 @@
+import { defineTheme } from '@mfeflow/theme';
+
+// Every token becomes a --mf-<token> variable on <html>. Remotes read them with var(--mf-color-fg).
+export const themes = [
+  defineTheme('light', {
+    'color-bg': '#ffffff',
+    'color-fg': '#111827',
+    'color-surface': '#f3f4f6',
+    'color-primary': '#2563eb',
+    'color-primary-fg': '#ffffff',
+    'color-border': '#e5e7eb',
+  }),
+  defineTheme(
+    'dark',
+    {
+      'color-bg': '#0b1020',
+      'color-fg': '#e5e7eb',
+      'color-surface': '#1f2937',
+      'color-primary': '#60a5fa',
+      'color-primary-fg': '#0b1020',
+      'color-border': '#374151',
+    },
+    { colorScheme: 'dark' },
+  ),
+];
+
+export const defaultTheme = 'light';
+
+// Use the system dark-mode setting when no theme is stored. The provider, the head script and the boot step all read this.
+export const followSystem = true;

package/assets/features/theming/files/tokens-test.ts

@@ -0,0 +1,9 @@
+import { describe, expect, it } from 'vitest';
+import { tokens } from './tokens';
+
+describe('tokens', () => {
+  it('are the shell variables, with a fallback for standalone runs', () => {
+    expect(tokens.primary).toBe('var(--mf-color-primary, #2563eb)');
+    expect(tokens.fg).toContain('--mf-color-fg');
+  });
+});

package/assets/features/theming/files/tokens.ts

@@ -0,0 +1,9 @@
+import { cssVar } from '@mfeflow/theme';
+
+// The shell sets these on <html>. The second argument is what a standalone run (no shell) falls back to.
+export const tokens = {
+  bg: cssVar('color-bg', '#ffffff'),
+  fg: cssVar('color-fg', '#111827'),
+  surface: cssVar('color-surface', '#f3f4f6'),
+  primary: cssVar('color-primary', '#2563eb'),
+};

package/assets/features/ui-shadcn/feature.json

@@ -0,0 +1,61 @@
+{
+  "name": "ui-shadcn",
+  "version": "0.1.0",
+  "description": "shadcn/ui in every remote, on top of tailwind: components.json, the cn helper and a Button, copied into the remote so you own them. The classes carry the remote's Tailwind prefix and the colours come from the theme. Nothing is shared between remotes.",
+  "requires": ["core", "tsconfig", "tailwind"],
+  "files": [
+    {
+      "to": "components.json",
+      "target": "remotes",
+      "from": "files/components.json.eta",
+      "template": true
+    },
+    {
+      "to": "src/lib/utils.ts",
+      "target": "remotes",
+      "from": "files/utils.ts.eta",
+      "template": true
+    },
+    {
+      "to": "src/components/ui/button.tsx",
+      "target": "remotes",
+      "from": "files/button.tsx.eta",
+      "template": true
+    },
+    {
+      "to": "src/lib/utils.test.ts",
+      "target": "remotes",
+      "from": "files/utils-test.ts.eta",
+      "template": true,
+      "when": {
+        "feature:testing": true
+      }
+    },
+    {
+      "to": "src/components/ui/button.test.tsx",
+      "target": "remotes",
+      "from": "files/button-test.tsx.eta",
+      "template": true,
+      "when": {
+        "feature:testing": true
+      }
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "class-variance-authority",
+      "range": "0.7.1",
+      "target": "remotes"
+    },
+    {
+      "name": "clsx",
+      "range": "2.1.1",
+      "target": "remotes"
+    },
+    {
+      "name": "tailwind-merge",
+      "range": "3.7.0",
+      "target": "remotes"
+    }
+  ]
+}

package/assets/features/ui-shadcn/files/button-test.tsx.eta

@@ -0,0 +1,32 @@
+<%_ const prefix = it.app.tailwindPrefix _%>
+import { fireEvent, render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+import { Button } from './button';
+
+const prefix = '<%= prefix %>';
+
+describe('Button', () => {
+  it('is a button that does not submit a form unless asked', () => {
+    render(<Button>Save</Button>);
+    expect(screen.getByRole('button', { name: 'Save' }).getAttribute('type')).toBe('button');
+  });
+
+  it('carries the remote prefix on its classes, and lets a caller override one', () => {
+    render(<Button className={`${prefix}:px-8`}>Save</Button>);
+    const { className } = screen.getByRole('button');
+    expect(className).toContain(`${prefix}:bg-primary`);
+    expect(className).toContain(`${prefix}:px-8`);
+    expect(className).not.toContain(`${prefix}:px-4`);
+  });
+
+  it('does not click while disabled', () => {
+    const onClick = vi.fn();
+    render(
+      <Button disabled onClick={onClick}>
+        Save
+      </Button>,
+    );
+    fireEvent.click(screen.getByRole('button'));
+    expect(onClick).not.toHaveBeenCalled();
+  });
+});

package/assets/features/ui-shadcn/files/button.tsx.eta

@@ -0,0 +1,36 @@
+<%_ const prefix = it.app.tailwindPrefix _%>
+import { cva, type VariantProps } from 'class-variance-authority';
+import type { ButtonHTMLAttributes } from 'react';
+import { cn } from '../../lib/utils';
+
+// Every class starts with <%= prefix %>: (this remote's Tailwind prefix). Colours are the theme tokens from src/styles.css.
+// prettier-ignore
+const buttonVariants = cva(
+  '<%= prefix %>:inline-flex <%= prefix %>:items-center <%= prefix %>:justify-center <%= prefix %>:gap-2 <%= prefix %>:rounded-md <%= prefix %>:text-sm <%= prefix %>:font-medium <%= prefix %>:transition-colors <%= prefix %>:disabled:pointer-events-none <%= prefix %>:disabled:opacity-50 <%= prefix %>:focus-visible:outline-2 <%= prefix %>:focus-visible:outline-offset-2 <%= prefix %>:focus-visible:outline-ring',
+  {
+    variants: {
+      variant: {
+        default: '<%= prefix %>:bg-primary <%= prefix %>:text-primary-foreground <%= prefix %>:hover:opacity-90',
+        secondary: '<%= prefix %>:bg-secondary <%= prefix %>:text-secondary-foreground <%= prefix %>:hover:opacity-80',
+        outline: '<%= prefix %>:border <%= prefix %>:border-border <%= prefix %>:bg-background <%= prefix %>:hover:bg-accent <%= prefix %>:hover:text-accent-foreground',
+        destructive: '<%= prefix %>:bg-destructive <%= prefix %>:text-white <%= prefix %>:hover:opacity-90',
+        ghost: '<%= prefix %>:hover:bg-accent <%= prefix %>:hover:text-accent-foreground',
+      },
+      size: {
+        default: '<%= prefix %>:h-9 <%= prefix %>:px-4 <%= prefix %>:py-2',
+        sm: '<%= prefix %>:h-8 <%= prefix %>:px-3',
+        lg: '<%= prefix %>:h-10 <%= prefix %>:px-6',
+      },
+    },
+    defaultVariants: { variant: 'default', size: 'default' },
+  },
+);
+
+export interface ButtonProps
+  extends ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {}
+
+export function Button({ className, variant, size, type = 'button', ...props }: ButtonProps) {
+  return (
+    <button type={type} className={cn(buttonVariants({ variant, size }), className)} {...props} />
+  );
+}

package/assets/features/ui-shadcn/files/components.json.eta

@@ -0,0 +1,22 @@
+<%_ const prefix = it.app.tailwindPrefix _%>
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "src/styles.css",
+    "baseColor": "neutral",
+    "cssVariables": false,
+    "prefix": "<%= prefix %>"
+  },
+  "aliases": {
+    "components": "@/components",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "utils": "@/lib/utils",
+    "hooks": "@/hooks"
+  },
+  "iconLibrary": "lucide"
+}

package/assets/features/ui-shadcn/files/utils-test.ts.eta

@@ -0,0 +1,17 @@
+<%_ const prefix = it.app.tailwindPrefix _%>
+import { describe, expect, it } from 'vitest';
+import { cn } from './utils';
+
+const prefix = '<%= prefix %>';
+
+describe('cn', () => {
+  it("keeps the last of two conflicting classes with this remote's prefix", () => {
+    expect(cn(`${prefix}:p-2`, `${prefix}:p-4`)).toBe(`${prefix}:p-4`);
+  });
+
+  it('skips false values and keeps classes that do not conflict', () => {
+    expect(cn(`${prefix}:flex`, false, undefined, `${prefix}:gap-2`)).toBe(
+      `${prefix}:flex ${prefix}:gap-2`,
+    );
+  });
+});

package/assets/features/ui-shadcn/files/utils.ts.eta

@@ -0,0 +1,11 @@
+<%_ const prefix = it.app.tailwindPrefix _%>
+import { clsx, type ClassValue } from 'clsx';
+import { extendTailwindMerge } from 'tailwind-merge';
+
+// Knows this remote's prefix, so cn('<%= prefix %>:p-2', '<%= prefix %>:p-4') keeps only the last one.
+const merge = extendTailwindMerge({ prefix: '<%= prefix %>' });
+
+/** Joins class names and drops the ones a later class overrides. */
+export function cn(...inputs: ClassValue[]): string {
+  return merge(clsx(inputs));
+}

package/assets/features/url-factory/files/endpoints.ts

@@ -4,9 +4,20 @@ export const endpoints = defineEndpoints({
   health: { service: 'api', path: '/health' },
 });
 
-const services: Record<string, string> = { api: '/api' };
+const defaults: Record<string, string> = { api: '/api' };
+
+// A service's base is `<service>Url` in the runtime config (apiUrl for api) when the shell loaded
+// one, so a build runs in every environment; the default above is for tests and standalone runs.
+function configured(service: string): string | undefined {
+  const config: unknown = Reflect.get(globalThis, '__MFE_RUNTIME_CONFIG__');
+  const value: unknown =
+    typeof config === 'object' && config !== null
+      ? Reflect.get(config, `${service}Url`)
+      : undefined;
+  return typeof value === 'string' && value !== '' ? value : undefined;
+}
 
 export const apiUrl = createUrlFactory(endpoints, (service) => {
-  const base = services[service];
+  const base = configured(service) ?? defaults[service];
   return base === undefined ? undefined : new URL(base, location.origin).toString();
 });

package/assets/templates/monorepo/feature.json

@@ -164,6 +164,12 @@
       "target": "root",
       "dev": true
     },
+    {
+      "name": "mfeflow",
+      "range": "latest",
+      "target": "root",
+      "dev": true
+    },
     {
       "name": "@mfeflow/runtime",
       "range": "latest",
@@ -271,6 +277,26 @@
       "command": "turbo run build",
       "target": "root"
     },
+    {
+      "name": "doctor",
+      "command": "mfeflow doctor",
+      "target": "root"
+    },
+    {
+      "name": "validate",
+      "command": "mfeflow validate",
+      "target": "root"
+    },
+    {
+      "name": "check-compat",
+      "command": "mfeflow check-compat",
+      "target": "root"
+    },
+    {
+      "name": "budget",
+      "command": "mfeflow budget",
+      "target": "root"
+    },
     {
       "name": "dev",
       "command": "rsbuild dev",

package/assets/templates/monorepo/files/root/AGENTS.md.eta

@@ -4,14 +4,14 @@ Guidance for coding agents working in this repo.
 
 - Package manager: pnpm (via corepack). Never npm or yarn. Versions live in the `catalog` of
   `pnpm-workspace.yaml`; add dependencies there and reference them as `catalog:`.
-- `pnpm dev` runs the shell and every remote. `pnpm build` builds all of them. `mfeflow dev` does the same with
+- `pnpm dev` runs the shell and every remote. `pnpm build` builds all of them. `pnpm mfeflow dev` does the same with
   per-app logs and picks up new remotes without a restart.
-- Before finishing: `mfeflow doctor` (and `mfeflow validate`, `mfeflow check-compat`, `mfeflow budget` after a build) must exit 0.
+- Before finishing: `pnpm doctor` (and `pnpm validate`, `pnpm check-compat`, `pnpm budget` after a build) must exit 0.
 - TypeScript 7, strict. Relative imports have no file extension (`./plan`, not `./plan.js`).
 - Each remote is deployed on its own. A remote must not import from another remote or from
   the shell; talk through the registry, events or URLs.
 - A remote's public surface is `src/exposed/`. Everything else is private to it.
-- Add apps and features with the `mfeflow` CLI (`mfeflow add remote <name>`, `mfeflow features`).
+- Add apps and features with the `mfeflow` CLI, installed as a root dev dependency (`pnpm mfeflow add remote <name>`, `pnpm mfeflow features`).
   `mfeflow.json` is the CLI's record of the project; do not edit the file hashes by hand.
 - Shared singletons (react, react-dom, `@mfeflow/runtime`) are provided by the shell. Do not
   bundle your own copy.

package/assets/templates/monorepo/files/root/README.md.eta

@@ -7,7 +7,7 @@ one shell and independently deployable remotes, loaded at runtime through Module
 apps/shell      the host: routes, layout, registry loading
 apps/<remote>   one micro-frontend each, exposing ./App
 registry/envs   which build of each remote every environment serves
-mfeflow.json    what the CLI generated; `mfeflow add` reads and updates it
+mfeflow.json    what the CLI generated; `pnpm mfeflow add` reads and updates it
 ```
 
 ## Run it
@@ -20,28 +20,28 @@ pnpm dev
 `pnpm dev` starts the shell on http://localhost:4300 and every remote on its own port
 (see `registry/envs/dev`). The shell reads that dev registry and renders the remotes.
 
-`mfeflow dev` does the same with a prefixed, coloured log per app, and it follows the project:
-add a remote with `mfeflow add remote checkout` and it starts, and the shell lists it, without a restart.
-Use a remote you already run elsewhere with `mfeflow dev --remote checkout=http://localhost:3001`,
+`pnpm mfeflow dev` does the same with a prefixed, coloured log per app, and it follows the project:
+add a remote with `pnpm mfeflow add remote checkout` and it starts, and the shell lists it, without a restart.
+Use a remote you already run elsewhere with `pnpm mfeflow dev --remote checkout=http://localhost:3001`,
 or run a few apps with `--only shell,catalog`. Ctrl+C stops everything.
 
 ## Change it
 
 ```sh
-mfeflow add remote checkout     # a new remote, its registry files and its shell route
-mfeflow add <feature>           # see `mfeflow features`
+pnpm mfeflow add remote checkout     # a new remote, its registry files and its shell route
+pnpm mfeflow add <feature>           # see `pnpm mfeflow features`
 ```
 
 ## Check it
 
 ```sh
-mfeflow doctor              # singletons, compatibility, config, drift; --fix repairs the safe ones
-mfeflow validate            # mfeflow.json, every mfe.json and every registry entry
-mfeflow check-compat        # each remote's shared ranges against its shell
-mfeflow budget              # after `pnpm build`: first-load JS per shell and remote
+pnpm doctor              # singletons, compatibility, config, drift; `pnpm doctor --fix` repairs the safe ones
+pnpm validate            # mfeflow.json, every mfe.json and every registry entry
+pnpm check-compat        # each remote's shared ranges against its shell
+pnpm budget              # after `pnpm build`: first-load JS per shell and remote
 ```
 
-All of them take `--json` and exit non-zero on errors, so they can run in CI. `mfeflow budget` checks each remote's entry
+Each is a root script for the `mfeflow` CLI in your devDependencies (`pnpm mfeflow <command>` runs it directly). All of them take `--json` and exit non-zero on errors, so they can run in CI. `pnpm budget` checks each remote's entry
 against the 10 KB a remote may add; set `budget.baselineKb` in `mfeflow.json` (your pages built as one app) to check
 the shell against baseline + 32 KB too.