@equinor/fusion-framework-cli 15.2.11 → 15.3.0

package/dist/esm/lib/utils/assert-object.js

@@ -20,6 +20,7 @@ import { assert } from './assert.js';
  */
 export function assertObject(value, message) {
     // typeof null is 'object', so this does not exclude null values
-    assert(typeof value === 'object', message);
+    // normalize to `Error | undefined` to match the `node:assert` overload
+    assert(typeof value === 'object', typeof message === 'string' ? new Error(message) : message);
 }
 //# sourceMappingURL=assert-object.js.map

package/dist/esm/lib/utils/assert-object.js.map

@@ -1 +1 @@
-{"version":3,"file":"assert-object.js","sourceRoot":"","sources":["../../../../src/lib/utils/assert-object.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,YAAY,CAAC,KAAa,EAAE,OAAwB;IAClE,gEAAgE;IAChE,MAAM,CAAC,OAAO,KAAK,KAAK,QAAQ,EAAE,OAAO,CAAC,CAAC;AAC7C,CAAC"}
+{"version":3,"file":"assert-object.js","sourceRoot":"","sources":["../../../../src/lib/utils/assert-object.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,YAAY,CAAC,KAAa,EAAE,OAAwB;IAClE,gEAAgE;IAChE,uEAAuE;IACvE,MAAM,CAAC,OAAO,KAAK,KAAK,QAAQ,EAAE,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;AAChG,CAAC"}

package/dist/esm/version.js

@@ -1,3 +1,3 @@
 // Generated by genversion.
-export const version = '15.2.11';
+export const version = '15.3.0';
 //# sourceMappingURL=version.js.map

package/dist/types/bin/serve-application.d.ts

@@ -32,6 +32,10 @@ export interface ServeApplicationOptions {
      * Enable debug mode for verbose logging.
      */
     debug?: boolean;
+    /**
+     * Origin of a local mock server to use for isolated service discovery and mock authentication.
+     */
+    mock?: string;
 }
 /**
  * Serves a built application using the dev-portal.

package/dist/types/bin/start-app-dev-server.d.ts

@@ -13,7 +13,7 @@ export interface StartAppDevServerOptions {
     /**
      * Runtime environment settings for the dev server (optional).
      */
-    env?: RuntimeEnv;
+    env?: Partial<RuntimeEnv>;
     /**
      * Path to the application manifest file (optional).
      */
@@ -34,6 +34,11 @@ export interface StartAppDevServerOptions {
      * Host for the development server (optional, defaults to 'localhost').
      */
     host?: string;
+    /**
+     * Origin of a local mock server (e.g. `http://localhost:4010`) to use for API service
+     * discovery instead of the default CI environment (optional).
+     */
+    mock?: string;
 }
 /**
  * Starts the application development server for local development.

package/dist/types/bin/utils/__tests__/fixtures/dev-mocks/foo.mock.d.ts

@@ -0,0 +1,6 @@
+declare const _default: {
+    key: string;
+    serviceDiscovery: string;
+    document: {};
+};
+export default _default;

package/dist/types/bin/utils/__tests__/fixtures/dev-mocks/service.mock.d.ts

@@ -0,0 +1,6 @@
+declare const _default: {
+    key: string;
+    serviceDiscovery: boolean;
+    document: {};
+};
+export default _default;

package/dist/types/bin/utils/apply-dev-server-mocks.d.ts

@@ -0,0 +1,12 @@
+import { type DevServerOptions } from '@equinor/fusion-framework-dev-server';
+import type { DevServerMockService } from './discover-dev-server-mocks.js';
+/**
+ * Adds discovered local mock services to a dev-server configuration.
+ *
+ * @param config - Loaded dev-server configuration, including any user-defined processor and routes.
+ * @param mocks - Local services derived from visible `defineService` modules.
+ * @returns A configuration where local services replace real entries by key.
+ * @throws {Error} When a mock marked as new collides with upstream service discovery.
+ */
+export declare function applyDevServerMocks(config: DevServerOptions, mocks: DevServerMockService[]): DevServerOptions;
+export default applyDevServerMocks;

package/dist/types/bin/utils/apply-dev-server-mocks.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/bin/utils/create-dev-server-config.d.ts

@@ -35,6 +35,8 @@ export type CreateDevServerOptions = {
         manifest: AppManifest;
         config?: ApiAppConfig;
     };
+    /** Origin of a local mock server (e.g. `http://localhost:4010`) to use for service discovery. */
+    mock?: string;
 };
 /**
  * Creates the full dev server configuration for Fusion CLI.
@@ -43,5 +45,5 @@ export type CreateDevServerOptions = {
  * @param options - Options for dev server config, including app/portal manifests and overrides.
  * @returns The complete dev server options object.
  */
-export declare const createDevServerConfig: (options: CreateDevServerOptions) => DevServerOptions;
+export declare const createDevServerConfig: (options: CreateDevServerOptions) => DevServerOptions<Partial<FusionTemplateEnv>>;
 export {};

package/dist/types/bin/utils/create-dev-server-config.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/bin/utils/discover-dev-server-mocks.d.ts

@@ -0,0 +1,20 @@
+import type { FusionService } from '@equinor/fusion-framework-dev-server';
+interface LocalMockService {
+    key: string;
+    serviceDiscovery: false | 'merge' | 'new' | 'replace';
+}
+/** Discovery-visible local mock service used by normal app development. */
+export interface DevServerMockService extends FusionService {
+    /** Controls collision behavior when overlaying upstream service discovery. */
+    serviceDiscovery: Exclude<LocalMockService['serviceDiscovery'], false>;
+}
+/**
+ * Discovers visible `defineService` modules for normal-development proxying.
+ *
+ * @param directory - Directory scanned non-recursively for dev-server mock definitions.
+ * @param port - Manually started standalone mock-server port.
+ * @returns Local service-discovery entries in deterministic filename order.
+ * @throws {Error} When the directory cannot be read or a discovered module has an invalid export.
+ */
+export declare function discoverDevServerMocks(directory: string, port: number): Promise<DevServerMockService[]>;
+export default discoverDevServerMocks;

package/dist/types/bin/utils/discover-dev-server-mocks.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/bin/utils/normalize-dev-server-config.d.ts

@@ -17,6 +17,8 @@ export declare const normalizeDevServerConfig: (config: DevServerOptions) => {
         clientId: string;
         redirectUri: string;
         requiresAuth: string;
+        mock?: string | boolean;
+        mockToken?: string;
     } | undefined;
     proxy: import("@equinor/fusion-framework-vite-plugin-spa").ResourceConfiguration[] | undefined;
     serviceDiscoveryUrl: string;

package/dist/types/cli/commands/app/dev.command.d.ts

@@ -19,6 +19,7 @@
  *   --env <environment>  Runtime environment for the dev server (default: local)
  *   --port <port>        Port for the development server (default: 3000)
  *   --host <host>        Host for the development server (default: localhost)
+ *   --mock [endpoint]    Point API service discovery at a local mock server (default: http://localhost:4010)
  *
  * Configuration:
  *   dev-server.config.ts  Optional configuration file for API mocking, service discovery,
@@ -29,9 +30,11 @@
  *   $ ffc app dev --port 4000
  *   $ ffc app dev --manifest ./app.manifest.local.ts --config ./app.config.ts
  *   $ ffc app dev --host 0.0.0.0
+ *   $ ffc app dev --mock
+ *   $ ffc app dev --mock http://localhost:5010
  *
  * @see startAppDevServer for implementation details
- * @see dev-server-config.md for configuration options
+ * @see {@link https://equinor.github.io/fusion-framework/cli/docs/dev-server/configuration.html | Dev server configuration guide}
  */
 export declare const command: import("node_modules/commander/typings/index.js").Command;
 export default command;

package/dist/types/cli/commands/app/dev.command.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/cli/commands/app/serve.command.d.ts

@@ -13,6 +13,7 @@
  *   $ ffc app serve
  *   $ ffc app serve --port 5000
  *   $ ffc app serve --dir ./dist --host 0.0.0.0
+ *   $ ffc app serve --mock
  *
  * Options:
  *   --port <port>        Port for the preview server (default: 4173)

package/dist/types/cli/commands/index.d.ts

@@ -3,9 +3,11 @@ export default _default;
 /**
  * Registers all built-in CLI commands and optional plugins on the Commander program.
  *
- * Built-in command groups: `app`, `auth`, `create`, `disco`, `portal`.
- * After registering built-in commands, loads any plugins declared in the
- * project's `fusion-cli.config` file.
+ * Built-in command groups: `app`, `auth`, `create`, `disco`, `portal`, `mock-server`.
+ * Configured plugins load before the optional `mock-server` fallback so an explicit
+ * `mockServerPlugin()` registration can retain its app-specific defaults. When no configured
+ * plugin owns that command, it delegates to the installed plugin package or registers an
+ * install-hint stub.
  *
  * @param program - The Commander program instance to register commands on.
  */

package/dist/types/cli/commands/portal/dev.command.d.ts

@@ -27,7 +27,7 @@
  *   $ ffc portal dev --debug
  *
  * @see startPortalDevServer for implementation details
- * @see dev-server-config.md for configuration options
+ * @see {@link https://equinor.github.io/fusion-framework/cli/docs/dev-server/configuration.html | Dev server configuration guide}
  */
 export declare const command: import("node_modules/commander/typings/index.js").Command;
 export default command;

package/dist/types/cli/commands/register-optional-mock-server-command.d.ts

@@ -0,0 +1,13 @@
+import type { Command } from 'commander';
+/**
+ * Registers `ffc mock-server` without requiring it to be declared in `fusion-cli.config.ts`.
+ *
+ * Delegates to `@equinor/fusion-framework-cli-plugin-mock-server` when it's installed;
+ * otherwise registers a stub command that tells the user how to install it. Either way,
+ * `ffc mock-server --help` (and the top-level command list) show the command, whether or
+ * not the optional plugin package is present.
+ *
+ * @param program - The Commander program instance to register the command on.
+ * @param packageName - Overridable for testing; defaults to the real plugin package name.
+ */
+export declare function registerOptionalMockServerCommand(program: Command, packageName?: string): Promise<void>;

package/dist/types/cli/commands/register-optional-mock-server-command.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/cli/plugins/is-module-not-found-error.d.ts

@@ -0,0 +1,8 @@
+/**
+ * True if `error` is Node's "module/package not found" error, for either CJS or ESM resolution.
+ *
+ * @param error - The value caught from a failed `import()` or `require()`.
+ * @param moduleName - Optional package name that must be identified as missing by the error.
+ * @returns Whether `error` represents the requested missing module/package.
+ */
+export declare function isModuleNotFoundError(error: unknown, moduleName?: string): boolean;

package/dist/types/cli/plugins/is-module-not-found-error.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/cli/plugins/resolve-optional-plugin.d.ts

@@ -0,0 +1,14 @@
+import type { Command } from 'commander';
+/**
+ * Dynamically imports an optional CLI plugin package's default export factory.
+ *
+ * Used to wire a specific, known plugin package into a built-in command without declaring
+ * it as a hard dependency of `@equinor/fusion-framework-cli` — the caller decides what to do
+ * (e.g. register a stub) when the package isn't installed.
+ *
+ * @param packageName - The npm package name to dynamically import.
+ * @returns The package's default export, called with no arguments; `null` if the package
+ * isn't installed.
+ * @throws The original error, for any failure other than the package not being found.
+ */
+export declare function resolveOptionalPlugin(packageName: string): Promise<((program: Command) => void) | null>;

package/dist/types/cli/plugins/resolve-optional-plugin.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/version.d.ts

@@ -1 +1 @@
-export declare const version = "15.2.11";
+export declare const version = "15.3.0";

package/docs/application.md

@@ -215,6 +215,13 @@ export default defineAppConfig((env, args) => {
 > [!IMPORTANT]
 > Endpoints defined here are **automatically registered as named HTTP clients** when the application initializes. You do not need to call `configureHttpClient(name, ...)` in `config.ts` for these endpoints — they are ready to use via `framework.modules.http.createClient('my-end-point')`. See the [HTTP client configuration docs](../../modules/http/docs/client-configuration.md) for details.
 
+> [!TIP]
+> To mock an app-owned `endpoints` client locally, use a `serviceDiscovery: false` executable
+> service and point `app.config.local.ts` at `http://<key>.localhost:4010`. See
+> [Mock an application-config endpoint locally](../../app/docs/http-clients.md#mock-an-application-config-endpoint-locally).
+> This direct workflow needs no `/@fusion-api` route or handwritten mock middleware. Restart
+> `ffc app dev` after changing `app.config.<env>.ts`.
+
 > [!TIP]
 > In `endpoints` you can also override Service Discovery urls. This might be useful when you are
 > testing in a PR-environment.
@@ -414,7 +421,6 @@ Start your application in development mode with hot reloading and environment-sp
 | `--debug`           | Enable debug mode for verbose logging.                              | `false`           |
 | `--manifest <path>` | Path to the app manifest file (`app.manifest[.env]?.[ts,js,json]`). | `app.manifest.ts` |
 | `--config <path>`   | Path to the app config file (`app.config[.env]?.[ts,js,json]`).     | `app.config.ts`   |
-| `--env <env>`       | Runtime environment for the dev server.                             | `local`           |
 | `--port <port>`     | Port for the development server.                                    | `3000`            |
 
 **Usage:**
@@ -446,6 +452,7 @@ The `serve` command serves your built application through the dev-portal, simila
 | `--dir <directory>` | Directory to serve (default: detected from build config).          |                   |
 | `--manifest <path>` | Path to the app manifest file (`app.manifest[.env]?.[ts,js,json]`). | `app.manifest.ts` |
 | `--config <path>`   | Path to the app config file (`app.config[.env]?.[ts,js,json]`).     | `app.config.ts`   |
+| `--mock [endpoint]` | Use isolated service discovery and mock authentication from a manually started mock server. | `http://localhost:4010` |
 | `-d`, `--debug`     | Enable debug mode for verbose logging.                              | `false`           |
 
 **Usage:**
@@ -459,6 +466,7 @@ pnpm fusion-framework-cli app serve
 pnpm fusion-framework-cli app serve --port 5000
 pnpm fusion-framework-cli app serve --dir ./dist --host 0.0.0.0
 pnpm fusion-framework-cli app serve --manifest app.manifest.prod.ts --config app.config.prod.ts
+ffc app serve --mock
 ```
 
 > [!IMPORTANT]
@@ -468,6 +476,14 @@ pnpm fusion-framework-cli app serve --manifest app.manifest.prod.ts --config app
 >
 > **Preview Environment**: The serve command uses production mode and marks the environment as preview, so the manifest uses the compiled entry point from your build output.
 
+> [!TIP]
+> Start `ffc mock-server` in another foreground terminal before using `--mock`. The `serve`
+> command does not own or start that process. Both `app dev` and `app serve` resolve the `local`
+> environment; pass explicit `--manifest` or `--config` paths when another file is needed. Mock
+> authentication signs in as `Test User` by default; see
+> [Generate a mock user and update `.env`](../../vite-plugins/spa/README.md#generate-a-mock-user-and-update-env)
+> to customize identity claims and token scopes.
+
 ### Publish
 
 Publish your application to the Fusion app store (registry) for deployment.

package/docs/dev-server-config.md

@@ -1,4 +1,15 @@
-The dev-server supports optional configuration through a `dev-server.config.ts` file in your project root. This allows you to customize how your application interacts with the Fusion Framework during development.
+# Configure `ffc app dev`
+
+The dev server supports optional configuration through a `dev-server.config.ts` file in your
+project root. Use it for SPA environment values, service-discovery endpoints, logging, and shared
+mock-server defaults.
+
+> [!IMPORTANT]
+> Define mocked service behavior in `mocks/<service>.mock.ts` with `defineService`. Do not handwrite
+> service mocks as `api.routes` or inject them with `api.processServices`; those are low-level
+> extension points for server-owned behavior and discovery transformations. Follow
+> [Migrate existing dev-server configuration](../../dev-server/docs/mocking.md#migrate-existing-dev-server-configuration)
+> to move existing mocks without discarding unrelated host configuration.
 
 > [!NOTE]
 > Basic server options like `port`, `host`, and `open` are configured via CLI flags or Vite configuration, not through `dev-server.config.ts`.
@@ -7,24 +18,24 @@ The dev-server supports optional configuration through a `dev-server.config.ts`
 
 The default dev-server configuration works for most applications, but you may want to customize it when:
 
-- **Testing API integrations**: Mock services or override API responses during development
+- **Configuring mock discovery**: Set shared mock directory, host, port, or seed defaults
 - **Debugging service discovery**: Filter or modify discovered services for testing
 - **Customizing the development environment**: Adjust template variables, CLI logging, or browser console logging
 - **Isolating development scenarios**: Configure different behaviors for different development stages
 
 ## Getting Started
 
-Create a `dev-server.config.ts` file in your project root. Start simple with object configuration:
+Most applications need no `dev-server.config.ts`. To mock a backend, start with the
+[mock-service guide](../../dev-server/docs/mocking.md) and create `mocks/<service>.mock.ts`. Existing
+applications can follow the guide's
+[migration steps](../../dev-server/docs/mocking.md#migrate-existing-dev-server-configuration).
+
+Create `dev-server.config.ts` only when the application needs shared server settings. Start with
+object configuration:
 
 ```typescript
-// Simple object configuration
 export default {
-  api: {
-    routes: [{
-      match: '/my-api/test',
-      middleware: (req, res) => res.end('OK')
-    }]
-  }
+  log: { level: 4 },
 };
 ```
 
@@ -35,15 +46,10 @@ import { defineDevServerConfig } from '@equinor/fusion-framework-cli';
 
 export default defineDevServerConfig(({ base }) => {
   // Access to base config and environment for advanced logic
-  const isLocalDev = process.env.USER === 'your-username'; // Example condition
+  const isDebug = process.env.DEBUG === 'true';
 
   return {
-    api: {
-      routes: [
-        // Different routes based on conditions
-        isLocalDev && { match: '/api/local-dev', middleware: localHandler }
-      ].filter(Boolean) // Remove falsy values
-    }
+    log: { level: isDebug ? 4 : base.log?.level },
   };
 });
 ```
@@ -58,22 +64,9 @@ For full TypeScript support and intellisense, import the configuration types:
 ```typescript
 import { defineDevServerConfig, type DevServerConfig } from '@equinor/fusion-framework-cli';
 
-// Fully typed configuration
 export default defineDevServerConfig(({ base }): DevServerConfig => ({
   ...base,
-  api: {
-    ...base.api,
-    routes: [
-      {
-        match: '/api/users',
-        middleware: (req, res) => {
-          // req and res are properly typed
-          res.setHeader('Content-Type', 'application/json');
-          res.end(JSON.stringify([]));
-        }
-      }
-    ]
-  }
+  log: { level: 4 },
 }));
 ```
 
@@ -88,8 +81,9 @@ The dev-server configuration supports these main areas:
 
 | Area | Purpose | Common Use Cases |
 |------|---------|------------------|
-| `api.routes` | Mock API endpoints | Testing UI without backend, error scenarios |
-| `api.processServices` | Modify service discovery | Add mock services, override endpoints |
+| `mockServer` | Shared mock-server defaults | Mock directory, host, port, deterministic seed |
+| `api.routes` | Add server-owned endpoints | Health checks or infrastructure callbacks |
+| `api.processServices` | Modify processed discovery | Advanced filtering or URI transformation |
 | `api.serviceDiscoveryUrl` | Change discovery endpoint | Custom/dev environments |
 | `spa.templateEnv` | Override Fusion config | Portal settings, MSAL config, telemetry |
 | `log` | Control CLI logging verbosity | Debug dev-server issues, reduce terminal noise |
@@ -103,13 +97,6 @@ Just export the properties you want to override:
 
 ```typescript
 export default {
-  // Only override what you need to change
-  api: {
-    routes: [{
-      match: '/api/users',
-      middleware: (req, res) => res.end(JSON.stringify([]))
-    }]
-  },
   spa: {
     templateEnv: {
       telemetry: { consoleLevel: 0 } // Only override telemetry
@@ -127,12 +114,7 @@ Use functions when you need conditional logic or access to runtime values:
 export default defineDevServerConfig(({ base }) => {
   // You have access to base config and runtime environment
   return {
-    api: {
-      routes: [
-        // Your routes automatically merge with any existing ones
-        { match: '/api/test', middleware: testHandler }
-      ]
-    }
+    log: { level: process.env.DEBUG === 'true' ? 4 : base.log?.level },
   };
 });
 ```
@@ -163,85 +145,51 @@ routes: [{ match: '/api/users', middleware: yourHandler }]
 ### I Need To...
 | I want to... | Configuration | Example |
 |--------------|---------------|---------|
-| Mock an API endpoint | `api.routes` | `routes: [{ match: '/api/users', middleware: (req, res) => res.end('[]') }]` |
-| Add a mock service | `api.processServices` | Add services to the service discovery response |
+| Mock a service | `mocks/<service>.mock.ts` | Use `defineService` and run `ffc mock-server` |
+| Configure mock defaults | `mockServer` | Set `path`, `host`, `port`, or `seed` |
+| Transform real discovery | `api.processServices` | Advanced: filter or rewrite processed services |
 | Override MSAL config | `spa.templateEnv.msal` | `msal: { clientId: 'dev-client-id' }` |
 | Change telemetry logging | `spa.templateEnv.telemetry` | `telemetry: { consoleLevel: 0 }` |
 | Reduce CLI noise | `log.level` | `log: { level: 2 }` |
 
 ## Essential Configurations
 
-### API Mocking
+### Mock services with executable modules
 
-**When you need it**: Your application depends on backend services that aren't available during development, or you want to test specific API responses without hitting real services.
+When a backend is unavailable or needs deterministic responses, install the optional mock-server
+plugin and create one executable module per service:
 
-**How it works**: Add custom routes that intercept API calls and return mock data.
+```sh
+pnpm add -D @equinor/fusion-framework-cli-plugin-mock-server
+```
 
 ```typescript
-export default defineDevServerConfig(() => ({
-  api: {
-    routes: [
-      {
-        match: '/api/users',
-        middleware: (req, res) => {
-          res.setHeader('Content-Type', 'application/json');
-          res.end(JSON.stringify([
-            { id: 1, name: 'John Doe', role: 'developer' },
-            { id: 2, name: 'Jane Smith', role: 'designer' }
-          ]));
-        }
-      },
-      // Mock error responses
-      {
-        match: '/api/users/404',
-        middleware: (req, res) => {
-          res.statusCode = 404;
-          res.end(JSON.stringify({ error: 'User not found' }));
-        }
-      }
-    ]
-  }
-}));
+// mocks/inventory.mock.ts
+import schema from './inventory.openapi.json' with { type: 'json' };
+import { defineService } from '@equinor/fusion-openapi-mock-server/discovery';
+
+export default defineService({
+  key: 'inventory',
+  serviceDiscovery: 'new',
+  schema,
+  components: {
+    InventoryItem: { name: () => 'Local item' },
+  },
+});
 ```
 
-**Benefits**: Develop UI components and user flows without backend dependencies. Test error handling scenarios easily.
-
-### Service Discovery Customization
+Run the standalone mock server in one terminal and the app in another:
 
-**When you need it**: You're developing against a service that doesn't exist yet in the remote service discovery, or you want to override service endpoints for local development.
-
-**How it works**: Add mock services to the service discovery response that your application can use during development.
-
-```typescript
-export default defineDevServerConfig(() => ({
-  api: {
-    processServices: (dataResponse) => {
-      const { data, routes } = dataResponse;
-
-      // Add mock services for development
-      const mockServices = [
-        {
-          key: 'my-new-service',
-          name: 'My New Service (Mock)',
-          uri: '/api/mock-service' // This will be proxied by the dev server
-        },
-        {
-          key: 'beta-feature-api',
-          name: 'Beta Feature API (Mock)',
-          uri: 'https://beta-api.example.com'
-        }
-      ];
-
-      return {
-        data: [...data, ...mockServices],
-        routes
-      };
-    }
-  }
-}));
+```sh
+ffc mock-server
+ffc app dev
 ```
 
-**Benefits**: Develop against planned services before they're deployed. Test integration scenarios with mock endpoints.
+Normal development keeps real discovery and overlays discovery-visible local modules by key. Use
+`ffc app dev --mock` when the app should resolve only bundled presets and local mock modules.
+
+See [Develop with mock services](../../dev-server/docs/mocking.md) for discovery modes and complete
+examples.
 
 ### Template Environment Variables
 
@@ -391,8 +339,10 @@ export default {
 - Check for TypeScript errors in config file
 
 ### Services Not Appearing
-- Ensure `processServices` returns `{ data: Service[], routes: Route[] }`
-- Verify you're not accidentally filtering out needed services
+- Confirm the mock server is running at `http://localhost:4010`.
+- Confirm the file matches `mocks/<service>.mock.ts` and default-exports `defineService(...)`.
+- Confirm `serviceDiscovery` is not `false` when the framework must resolve the service by key.
+- In `--mock` mode, include every required service through a bundled preset or local module.
 
 ### Template Variables Not Available
 - Variables are injected as `import.meta.env.FUSION_SPA_*`
@@ -415,3 +365,73 @@ export default {
 > [!WARNING]
 > Only use when working with non-standard environments. The default Fusion service discovery endpoint is usually correct.
 
+### Transform service discovery and add custom routes
+
+Use `api.processServices` when the dev server must filter or transform the processed service
+discovery response. Call the default `processServices` helper first to preserve local URI rewriting
+and generated proxy routes. Use `api.routes` for server-owned endpoints that do not represent a
+mocked service:
+
+```typescript
+import { defineDevServerConfig } from '@equinor/fusion-framework-cli';
+import { processServices } from '@equinor/fusion-framework-dev-server';
+
+export default defineDevServerConfig(() => ({
+  api: {
+    processServices: (data, args) => {
+      const processed = processServices(data, args);
+      return {
+        ...processed,
+        data: processed.data.filter((service) => service.key !== 'deprecated-service'),
+      };
+    },
+    routes: [
+      {
+        match: '/health',
+        middleware: (_request, response) => {
+          response.setHeader('content-type', 'application/json');
+          response.end(JSON.stringify({ status: 'ready' }));
+        },
+      },
+    ],
+  },
+}));
+```
+
+Defining `api.processServices` replaces the default processing entry point. Omit the helper call
+only when the host intentionally owns all service URI rewriting and proxy-route generation. Route
+entries are merged by `match`, and a route from `dev-server.config.ts` replaces a base route with
+the same path.
+
+These extension points remain available for custom hosts and infrastructure. Define application
+service behavior in `mocks/<service>.mock.ts` so discovery metadata, OpenAPI operations, and mock
+responses stay in one executable module.
+
+### Local mock server
+
+The recommended workflow needs no `api.routes` or `api.processServices` configuration. Start the
+foreground mock server, then choose normal overlay or isolated development:
+
+```sh
+ffc mock-server
+ffc app dev                               # real discovery plus visible local modules
+ffc app dev --mock                        # bundled presets plus local modules only
+```
+
+`--mock` sets `api.serviceDiscoveryUrl` to `<endpoint>/@fusion-mock/discovery`. A
+`dev-server.config.ts` override for `api.serviceDiscoveryUrl` still takes precedence over it.
+The mode also enables mock authentication with `Test User`; see
+[Generate a mock user and update `.env`](../../vite-plugins/spa/README.md#generate-a-mock-user-and-update-env)
+to set identity claims and space-separated `scp` token scopes.
+
+Use `dev-server.config.ts` only to share mock-server defaults such as a nonstandard path or port:
+
+```typescript
+import type {} from '@equinor/fusion-framework-cli-plugin-mock-server';
+import { defineDevServerConfig } from '@equinor/fusion-framework-cli';
+
+export default defineDevServerConfig(() => ({
+  mockServer: { path: 'mocks', port: 4010, seed: 42 },
+}));
+```
+