proteum 2.5.9 → 2.5.10

package/agents/project/tests/AGENTS.md

@@ -9,9 +9,9 @@ Diagnostics source of truth: root-level `diagnostics.md`.
 
 - Understand the real user flow and the main feature branches before writing tests.
 - Test the current controller/page runtime model, not legacy `@Route` or `api.fetch(...)` behavior.
-- For every production change, add or update focused unit tests and run the targeted test command that matches the changed behavior. When the repository defines `proteum.verify.config.ts`, use `npx proteum verify changed` first so changed test files, related source tests, and project-specific suites are selected consistently. Do not run whole-project coverage after every ordinary change by default. Downstream app commit-only workflows run only `proteum refresh`, then targeted lint, typecheck, and test commands in parallel; framework-repo commit workflows skip this downstream app verification. Use `npm run check` as the full gate before push or when the user explicitly asks for it, and document any generated files, migrations, framework shims, unreachable defensive branches, or changes that cannot reasonably be unit-tested as explicit exceptions.
+- For every production change, add or update focused unit tests and run the targeted test command that matches the changed behavior. When the repository defines `proteum.verify.config.ts`, use `npx proteum verify changed` first so changed test files, related source tests, and project-specific suites are selected consistently. Coverage, commit-time, and push-time gates follow the root contract `Verification Policy` and `Commit Workflow`.
 - Verify routing, controllers, SSR, and router plugins against a running app when behavior depends on real request handling.
-- After implementing a new feature or changing existing feature behavior, update the end-to-end coverage for that behavior and run the full Playwright suite before finishing. Prefer `npx proteum e2e --port <port>` for Playwright runs so base URLs and auth tokens are passed through Proteum-managed child env instead of shell-leading environment assignments. Use a browser MCP repro against a running app during iteration when it is the fastest trustworthy loop.
+- After implementing a new feature or changing existing feature behavior, update the end-to-end coverage for that behavior and run the targeted Playwright scenarios that cover it before finishing; reserve the full suite for push workflows or explicit requests per the root contract `Verification Policy`. Prefer `npx proteum e2e --port <port>` for Playwright runs so base URLs and auth tokens are passed through Proteum-managed child env instead of shell-leading environment assignments. For new UI-visible features, the root `Verification Policy` still requires a browser MCP pass against the real page before finishing.
 - Exercise real URLs, generated controller calls, or real browser flows instead of re-deriving framework internals in tests.
 - Organize end-to-end tests following the Crosspath platform layout under `tests/e2e/**`.
 - Put runnable scenario entrypoints in `tests/e2e/features/**`, `tests/e2e/specs/<domain>/**`, or `tests/e2e/journeys/**` depending on scope.
@@ -23,7 +23,7 @@ Diagnostics source of truth: root-level `diagnostics.md`.
 - Add `data-testid` where needed instead of relying on brittle selectors.
 - Keep end-to-end tests clean, well organized, and non-redundant. Prefer extending or reshaping the most relevant existing scenario over duplicating coverage, and remove or consolidate overlap when the suite becomes repetitive.
 - Reuse root catalog files from `/client/catalogs/**`, `/server/catalogs/**`, or `/common/catalogs/**` instead of duplicating catalog constants in tests.
-- For protected dev flows, prefer `npx proteum e2e --session-email <email> --session-role <role>` or `npx proteum session <email> --role <role>` over automating login unless the login flow itself is under test.
+- For browser MCP validation in dev, start from the project instructions' admin account with `npx proteum session <admin-email> --role GOD` or its `browserLoginUrl` unless the scenario intentionally covers auth, anonymous, or non-admin behavior. For protected E2E dev flows, prefer `npx proteum e2e --session-email <email> --session-role <role>` over automating login unless the login flow itself is under test.
 
 ### Real-World Journey E2E
 

package/cli/commands/session.ts

@@ -4,7 +4,13 @@ import { spawn } from 'child_process';
 import { UsageError } from 'clipanion';
 
 import cli from '..';
-import type { TDevSessionErrorResponse, TDevSessionStartResponse } from '../../common/dev/session';
+import {
+    buildDevSessionLoginUrl,
+    devSessionStartPath,
+    normalizeDevSessionRedirectPath,
+    type TDevSessionErrorResponse,
+    type TDevSessionStartResponse,
+} from '../../common/dev/session';
 
 const localSessionResultMarker = '__PROTEUM_SESSION_RESULT__';
 
@@ -13,6 +19,7 @@ type TResolvedSessionOutput = {
     user: TDevSessionStartResponse['user'];
     session: TDevSessionStartResponse['session'];
     browserCookie: string;
+    browserLoginUrl: string;
     curlCookieHeader: string;
     playwright: {
         cookies: Array<{
@@ -28,6 +35,13 @@ type TResolvedSessionOutput = {
 };
 
 const normalizeBaseUrl = (value: string) => value.replace(/\/+$/, '');
+const normalizeRedirectPath = (value: string): string => {
+    try {
+        return normalizeDevSessionRedirectPath(value);
+    } catch (error) {
+        throw new UsageError(error instanceof Error ? error.message : String(error));
+    }
+};
 
 const getRouterPortFromManifest = () => {
     const manifestFilepath = path.join(cli.args.workdir as string, '.proteum', 'manifest.json');
@@ -82,7 +96,7 @@ const requestSession = async (email: string, role: string) => {
 
     for (const baseUrl of getRouterBaseUrls()) {
         try {
-            const response = await got(`${baseUrl}/__proteum/session/start`, {
+            const response = await got(`${baseUrl}${devSessionStartPath}`, {
                 method: 'POST',
                 json: role ? { email, role } : { email },
                 responseType: 'json',
@@ -92,7 +106,7 @@ const requestSession = async (email: string, role: string) => {
 
             if (response.statusCode >= 400) {
                 if (response.statusCode === 404 && !hasStructuredSessionError(response.body as TDevSessionErrorResponse | object | string | undefined)) {
-                    attempts.push(`${baseUrl}/__proteum/session/start: returned 404`);
+                    attempts.push(`${baseUrl}${devSessionStartPath}: returned 404`);
                     continue;
                 }
 
@@ -109,7 +123,7 @@ const requestSession = async (email: string, role: string) => {
             if (error instanceof UsageError) throw error;
 
             const message = error instanceof Error ? error.message : String(error);
-            attempts.push(`${baseUrl}/__proteum/session/start: ${message}`);
+            attempts.push(`${baseUrl}${devSessionStartPath}: ${message}`);
         }
     }
 
@@ -124,9 +138,13 @@ const requestSession = async (email: string, role: string) => {
 
 const buildSessionOutput = ({
     baseUrl,
+    redirect,
+    role,
     response,
 }: {
     baseUrl: string;
+    redirect: string;
+    role: string;
     response: TDevSessionStartResponse;
 }): TResolvedSessionOutput => {
     const expires = Math.floor(Date.parse(response.session.expiresAt) / 1000);
@@ -137,6 +155,12 @@ const buildSessionOutput = ({
         user: response.user,
         session: response.session,
         browserCookie: `${response.session.cookieName}=${response.session.token}; Path=/`,
+        browserLoginUrl: buildDevSessionLoginUrl({
+            baseUrl,
+            email: response.user.email,
+            redirect,
+            role,
+        }),
         curlCookieHeader: `Cookie: ${response.session.cookieName}=${response.session.token}`,
         playwright: {
             cookies: [
@@ -170,6 +194,8 @@ const renderSession = (value: TResolvedSessionOutput) =>
         JSON.stringify(value.playwright, null, 2),
         'Browser Cookie',
         value.browserCookie,
+        'Browser Login URL',
+        value.browserLoginUrl,
     ].join('\n');
 
 const runLocalSession = async (email: string, role: string) => {
@@ -232,6 +258,7 @@ const runLocalSession = async (email: string, role: string) => {
 export const run = async () => {
     const email = typeof cli.args.email === 'string' ? cli.args.email.trim() : '';
     const role = typeof cli.args.role === 'string' ? cli.args.role.trim() : '';
+    const redirect = normalizeRedirectPath(typeof cli.args.redirect === 'string' ? cli.args.redirect : '/');
     const shouldPrintJson = cli.args.json === true;
     const shouldUseRemoteServer =
         (typeof cli.args.port === 'string' && cli.args.port.length > 0) ||
@@ -242,7 +269,11 @@ export const run = async () => {
     }
 
     const resolved = buildSessionOutput(
-        shouldUseRemoteServer ? await requestSession(email, role) : await runLocalSession(email, role),
+        {
+            ...(shouldUseRemoteServer ? await requestSession(email, role) : await runLocalSession(email, role)),
+            redirect,
+            role,
+        },
     );
 
     if (shouldPrintJson) {

package/cli/commands/verify.ts

@@ -1149,7 +1149,12 @@ const runChangedVerify = async () => {
             code: 'changed/check-failed',
             message: `Verification check "${execution.checkId}" failed with exit code ${execution.exitCode ?? 'unknown'}.`,
             source: 'changed',
-            details: [`command=${execution.command}`, `cwd=${execution.cwd}`, `durationMs=${execution.durationMs}`],
+            details: [
+                `command=${execution.command}`,
+                `cwd=${execution.cwd}`,
+                `durationMs=${execution.durationMs}`,
+                'fix=Fix the failing surface and re-run npx proteum verify changed; broader gates only per the root AGENTS.md Verification Policy.',
+            ],
         }));
 
     return finalizeResult({

package/cli/compiler/client/index.ts

@@ -12,6 +12,7 @@ import { rspack, type Configuration, type Module } from '@rspack/core';
 import createCommonConfig, { TCompileMode, TCompileOutputTarget, regex } from '../common';
 import { createClientBundleAnalysisPlugins } from '../common/bundleAnalysis';
 import { toRspackAliases } from '../common/rspackAliases';
+import { resolveUiSingletonAliases } from '../common/uiSingletons';
 import identityAssets from './identite';
 import cli from '../..';
 import { logVerbose } from '../../runtime/verbose';
@@ -35,7 +36,9 @@ const getFrameworkSourceRoot = () => {
     return activeCoreRoot;
 };
 
-const resolveFromAppOrCore = (_app: App, request: string) => cli.paths.resolveRequest(request);
+const resolveFromAppOrCore = (request: string) => cli.paths.resolveRequest(request, { preferApp: true });
+const resolvePackageRootFromAppOrCore = (packageName: string) =>
+    cli.paths.resolvePackageRoot(packageName, { preferApp: true });
 const rewriteFrameworkAliasTargets = (aliases: Record<string, string | string[]>) => {
     const visibleFrameworkRoots = [
         ...cli.paths.getVisiblePackageInstallRoots('proteum'),
@@ -145,9 +148,13 @@ export default function createCompiler(
     const rspackAliases = toRspackAliases(resolvedAliases);
     rspackAliases['proteum'] = frameworkSourceRoot;
     rspackAliases['@/client/router$'] = frameworkSourceRoot + '/client/router.ts';
-    rspackAliases['preact/jsx-runtime$'] = resolveFromAppOrCore(app, 'preact/jsx-runtime');
-    rspackAliases['react/jsx-runtime$'] = resolveFromAppOrCore(app, 'preact/jsx-runtime');
-    rspackAliases['react/jsx-dev-runtime$'] = resolveFromAppOrCore(app, 'preact/jsx-dev-runtime');
+    Object.assign(
+        rspackAliases,
+        resolveUiSingletonAliases({
+            resolvePackageRoot: resolvePackageRootFromAppOrCore,
+            resolveRequest: resolveFromAppOrCore,
+        }),
+    );
 
     debug && console.log('client aliases', rspackAliases);
     const config: Configuration = {

package/cli/compiler/common/uiSingletons.ts

@@ -0,0 +1,76 @@
+type TUiSingletonResolvers = {
+    resolvePackageRoot: (packageName: string) => string;
+    resolveRequest: (request: string) => string;
+};
+
+const uiSingletonPackages = ['preact', 'preact-render-to-string', 'react', 'react-dom'];
+
+const uiSingletonPackageAliases: Array<{ alias: string; packageName: string }> = [
+    { alias: 'preact', packageName: 'preact' },
+    { alias: 'preact-render-to-string', packageName: 'preact-render-to-string' },
+];
+
+const uiSingletonRequestAliases: Array<{ alias: string; request: string }> = [
+    { alias: 'preact$', request: 'preact' },
+    { alias: 'preact/hooks$', request: 'preact/hooks' },
+    { alias: 'preact/compat$', request: 'preact/compat' },
+    { alias: 'preact/compat/client$', request: 'preact/compat/client' },
+    { alias: 'preact/jsx-runtime$', request: 'preact/jsx-runtime' },
+    { alias: 'preact/jsx-dev-runtime$', request: 'preact/jsx-dev-runtime' },
+    { alias: 'react$', request: 'preact/compat' },
+    { alias: 'react-dom$', request: 'preact/compat' },
+    { alias: 'react-dom/client$', request: 'preact/compat/client' },
+    { alias: 'react-dom/test-utils$', request: 'preact/test-utils' },
+    { alias: 'react/jsx-runtime$', request: 'preact/jsx-runtime' },
+    { alias: 'react/jsx-dev-runtime$', request: 'preact/jsx-dev-runtime' },
+    { alias: 'preact-render-to-string$', request: 'preact-render-to-string' },
+];
+
+const uiSingletonServerExternalRequests: Array<{ request: string; resolvedRequest: string }> = [
+    { request: 'preact', resolvedRequest: 'preact' },
+    { request: 'preact/hooks', resolvedRequest: 'preact/hooks' },
+    { request: 'preact/compat', resolvedRequest: 'preact/compat' },
+    { request: 'preact/compat/client', resolvedRequest: 'preact/compat/client' },
+    { request: 'preact/jsx-runtime', resolvedRequest: 'preact/jsx-runtime' },
+    { request: 'preact/jsx-dev-runtime', resolvedRequest: 'preact/jsx-dev-runtime' },
+    { request: 'preact/test-utils', resolvedRequest: 'preact/test-utils' },
+    { request: 'react', resolvedRequest: 'preact/compat' },
+    { request: 'react-dom', resolvedRequest: 'preact/compat' },
+    { request: 'react-dom/client', resolvedRequest: 'preact/compat/client' },
+    { request: 'react-dom/test-utils', resolvedRequest: 'preact/test-utils' },
+    { request: 'react/jsx-runtime', resolvedRequest: 'preact/jsx-runtime' },
+    { request: 'react/jsx-dev-runtime', resolvedRequest: 'preact/jsx-dev-runtime' },
+];
+
+export const isUiSingletonRequest = (request: string | undefined) =>
+    typeof request === 'string' &&
+    uiSingletonPackages.some((packageName) => request === packageName || request.startsWith(`${packageName}/`));
+
+export const resolveUiSingletonAliases = ({ resolvePackageRoot, resolveRequest }: TUiSingletonResolvers) => ({
+    ...Object.fromEntries(
+        uiSingletonRequestAliases.map(({ alias, request }) => [
+            alias,
+            resolveRequest(request),
+        ]),
+    ),
+    ...Object.fromEntries(
+        uiSingletonPackageAliases.map(({ alias, packageName }) => [
+            alias,
+            resolvePackageRoot(packageName),
+        ]),
+    ),
+});
+
+export const resolveUiSingletonServerExternalRequest = (
+    request: string | undefined,
+    resolveRequest: TUiSingletonResolvers['resolveRequest'],
+) => {
+    if (request === undefined) return undefined;
+
+    const exactExternalRequest = uiSingletonServerExternalRequests.find((entry) => entry.request === request);
+    if (exactExternalRequest) return resolveRequest(exactExternalRequest.resolvedRequest);
+
+    if (request.startsWith('preact/')) return resolveRequest(request);
+
+    return undefined;
+};

package/cli/compiler/server/index.ts

@@ -10,6 +10,11 @@ import { type Configuration } from '@rspack/core';
 import cli from '@cli';
 import createCommonConfig, { TCompileMode, TCompileOutputTarget, regex } from '../common';
 import { toRspackAliases } from '../common/rspackAliases';
+import {
+    isUiSingletonRequest,
+    resolveUiSingletonAliases,
+    resolveUiSingletonServerExternalRequest,
+} from '../common/uiSingletons';
 import { resolveServerExternalRequest } from './externals';
 
 // Type
@@ -51,6 +56,9 @@ const getDevGeneratedRuntimeEntries = (app: App) => ({
     __proteum_dev_routes: [app.paths.server.generated + '/routes.ts'],
     __proteum_dev_controllers: [app.paths.server.generated + '/controllers.ts'],
 });
+const resolveFromAppOrCore = (request: string) => cli.paths.resolveRequest(request, { preferApp: true });
+const resolvePackageRootFromAppOrCore = (packageName: string) =>
+    cli.paths.resolvePackageRoot(packageName, { preferApp: true });
 const normalizeModulePath = (value?: string) => (value || '').replace(/\\/g, '/');
 const getFrameworkSourceRoot = () => {
     const installedCoreRoot = cli.paths.framework.installedRoot
@@ -120,6 +128,13 @@ export default function createCompiler(
     const rspackAliases = toRspackAliases(resolvedAliases);
     rspackAliases['proteum'] = frameworkSourceRoot;
     rspackAliases['@/client/router$'] = frameworkSourceRoot + '/client/router.ts';
+    Object.assign(
+        rspackAliases,
+        resolveUiSingletonAliases({
+            resolvePackageRoot: resolvePackageRootFromAppOrCore,
+            resolveRequest: resolveFromAppOrCore,
+        }),
+    );
 
     debug &&
         console.log(
@@ -160,20 +175,27 @@ export default function createCompiler(
 
             // node_modules
             function ({ context, request }, callback) {
+                if (request === undefined) return callback();
+
+                const uiSingletonExternalRequest = resolveUiSingletonServerExternalRequest(request, resolveFromAppOrCore);
+                if (uiSingletonExternalRequest !== undefined) {
+                    return callback(undefined, 'commonjs ' + uiSingletonExternalRequest);
+                }
+
                 const shouldCompile =
-                    request !== undefined &&
                     // Local files
-                    (request[0] === '.' ||
-                        request[0] === '/' ||
-                        // Aliased modules
-                        app.aliases.server.containsAlias(request) ||
-                        // TODO: proteum.conf: compile: include
-                        app.isTranspileModuleRequest(request) ||
-                        // Compile proteum modules
-                        request.startsWith('proteum') ||
-                        // React-based UI packages must pass through the alias layer on the server,
-                        // otherwise SSR can mix real React packages with the Preact compat runtime.
-                        serverReactCompatCompilePrefixes.some((prefix) => request.startsWith(prefix)));
+                    request[0] === '.' ||
+                    request[0] === '/' ||
+                    // Aliased modules
+                    app.aliases.server.containsAlias(request) ||
+                    // TODO: proteum.conf: compile: include
+                    app.isTranspileModuleRequest(request) ||
+                    // Compile proteum modules
+                    request.startsWith('proteum') ||
+                    // React/Preact singleton packages and React-based UI packages must pass through the alias layer on the server,
+                    // otherwise SSR can mix real React packages with the Preact compat runtime.
+                    isUiSingletonRequest(request) ||
+                    serverReactCompatCompilePrefixes.some((prefix) => request.startsWith(prefix));
 
                 //console.log('isNodeModule', request, isNodeModule);
 

package/cli/presentation/commands.ts

@@ -594,7 +594,7 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         name: 'session',
         category: 'Manifest and contracts',
         summary: 'Mint a dev-only auth session token and cookie payload for a known user.',
-        usage: 'proteum session <email> [--role <role>] [--port <port>|--url <baseUrl>] [--json]',
+        usage: 'proteum session <email> [--role <role>] [--redirect <path>] [--port <port>|--url <baseUrl>] [--json]',
         bestFor:
             'Starting browser or API automation from an authenticated state without driving the login UI, while still using the app-configured auth service.',
         examples: [
@@ -606,11 +606,16 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
                 description: 'Mint a GOD session for unique.domains and print machine-readable cookie data',
                 command: 'proteum session god@example.com --role GOD --json',
             },
+            {
+                description: 'Print a browser login URL that sets the cookie and opens a protected page',
+                command: 'proteum session admin@example.com --port 3101 --redirect /admin --json',
+            },
         ],
         notes: [
             'Sessions are available only in dev mode and use the auth service registered on the current app router.',
             'You must provide the target user email explicitly; Proteum does not guess your admin account universally across apps.',
             'The command returns a token plus Playwright-ready cookie JSON so agents can inject the session into a browser context directly.',
+            'The command also returns a browser login URL that works on localhost dev servers, sets the same session cookie, and redirects to a local path.',
             'Without `--port` or `--url`, Proteum refreshes generated artifacts, builds the dev output, starts a temporary local dev server, creates the session, prints the payload, and exits.',
         ],
         status: 'experimental',

package/cli/runtime/commands.ts

@@ -617,6 +617,7 @@ class SessionCommand extends ProteumCommand {
     public role = Option.String('--role', { description: 'Require the resolved user to have the given role.' });
     public port = Option.String('--port', { description: 'Target an existing dev server on the given port.' });
     public url = Option.String('--url', { description: 'Target an existing dev server at the given base URL.' });
+    public redirect = Option.String('--redirect', { description: 'Local path used by the browser login URL.' });
     public json = Option.Boolean('--json', false, { description: 'Print JSON output.' });
     public args = Option.Rest();
 
@@ -628,6 +629,7 @@ class SessionCommand extends ProteumCommand {
             role: this.role ?? '',
             port: this.port ?? '',
             url: this.url ?? '',
+            redirect: this.redirect ?? '',
             json: this.json,
         });
 

package/cli/scaffold/index.ts

@@ -556,6 +556,9 @@ export const runCreateScaffold = async () => {
 
     result.notes.push(...plan.notes);
     result.nextSteps.push(...plan.nextSteps);
+    result.nextSteps.push(
+        'Adapt the generated code to the real feature and record non-obvious decisions as why-comments per `CODING_STYLE.md` (`Decision and context comments`).',
+    );
     printResult(result);
 };
 

package/cli/scaffold/templates.ts

@@ -22,7 +22,15 @@ export const createPageTemplate = ({
     routePath: string;
     heading: string;
     message: string;
-}) => `import { definePageRoute } from '@common/router/definitions';
+}) => `/*----------------------------------
+- DEPENDANCES
+----------------------------------*/
+
+import { definePageRoute } from '@common/router/definitions';
+
+/*----------------------------------
+- PAGE
+----------------------------------*/
 
 export default definePageRoute({
     path: ${JSON.stringify(routePath)},
@@ -53,7 +61,15 @@ export const createControllerTemplate = ({
     appIdentifier: string;
     className: string;
     methodName: string;
-}) => `import { defineAction, defineController } from '@generated/server/controller';
+}) => `/*----------------------------------
+- DEPENDANCES
+----------------------------------*/
+
+import { defineAction, defineController } from '@generated/server/controller';
+
+/*----------------------------------
+- CONTROLEUR
+----------------------------------*/
 
 export default defineController({
     actions: {
@@ -74,11 +90,23 @@ export const createCommandTemplate = ({
 }: {
     className: string;
     methodName: string;
-}) => `import { Commands } from '@server/app/commands';
+}) => `/*----------------------------------
+- DEPENDANCES
+----------------------------------*/
+
+import { Commands } from '@server/app/commands';
 import type AppApplication from '@/server/index';
 
+/*----------------------------------
+- TYPES
+----------------------------------*/
+
 type App = InstanceType<typeof AppApplication>;
 
+/*----------------------------------
+- COMMANDS
+----------------------------------*/
+
 export default class ${className} extends Commands<App> {
     public async ${methodName}() {
         return {
@@ -95,7 +123,15 @@ export const createRouteTemplate = ({
 }: {
     httpMethod: string;
     routePath: string;
-}) => `import { defineServerRoute } from '@common/router/definitions';
+}) => `/*----------------------------------
+- DEPENDANCES
+----------------------------------*/
+
+import { defineServerRoute } from '@common/router/definitions';
+
+/*----------------------------------
+- ROUTES
+----------------------------------*/
 
 export default defineServerRoute({
     method: ${JSON.stringify(httpMethod.toUpperCase())},
@@ -115,12 +151,24 @@ export const createServiceTemplate = ({
 }: {
     appIdentifier: string;
     className: string;
-}) => `import Service from '@server/app/service';
+}) => `/*----------------------------------
+- DEPENDANCES
+----------------------------------*/
+
+import Service from '@server/app/service';
+
+/*----------------------------------
+- TYPES
+----------------------------------*/
 
 export type Config = {
     debug?: boolean;
 };
 
+/*----------------------------------
+- SERVICE
+----------------------------------*/
+
 export default class ${className} extends Service<Config, {}, ${appIdentifier}, ${appIdentifier}> {
     public async health() {
         return {
@@ -138,9 +186,17 @@ export const createServiceConfigTemplate = ({
     configExportName: string;
     serviceImportPath: string;
     serviceImportName: string;
-}) => `import { Services } from '@server/app';
+}) => `/*----------------------------------
+- DEPENDANCES
+----------------------------------*/
+
+import { Services } from '@server/app';
 import ${serviceImportName} from ${JSON.stringify(serviceImportPath)};
 
+/*----------------------------------
+- CONFIG
+----------------------------------*/
+
 export const ${configExportName} = Services.config(${serviceImportName}, {});
 `;
 

package/cli/utils/agents.ts

@@ -1053,11 +1053,11 @@ function renderEmbeddedProjectInstructions({
         '- Worktree Preflight (`cwd` inside `/.codex/worktrees/`, newly created Proteum worktree, or before editing in a Codex worktree): read Root contract fallback, run `npx proteum worktree init --source <source-app-root>` when the bootstrap marker is missing, run `npx proteum worktree init --source <source-app-root> --refresh` when Proteum reports stale bootstrap state, use `--skip-deps --reason "..."` only for intentional dependency skips, then run `npx proteum runtime status`; for runtime-visible work start or reuse one tracked `npx proteum dev` session using the Task Lifecycle launch workflow.',
         '- Git lifecycle (`commit`, `and commit`, `stage`, `push`, `PR`, pull request): read Root contract fallback before any git write.',
         '- Before git writes after a bug fix, behavior change, decision change, or docs-relevant production change: read `DOCUMENTATION.md` and verify required docs, fix notes, or ADRs were updated or explicitly skipped with a reason.',
-        '- Before finishing production code changes: read Root contract fallback, `DOCUMENTATION.md`, `CODING_STYLE.md`, `tests/AGENTS.md`, and any touched area `AGENTS.md`.',
+        '- Before finishing production code changes: read Root contract fallback, `DOCUMENTATION.md`, `CODING_STYLE.md`, `tests/AGENTS.md`, and any touched area `AGENTS.md`. Run the `CODING_STYLE.md` self-check on the final diff; a non-obvious decision, workaround, or bug fix without a why-comment is a defect to fix before finishing.',
         '- Runtime-visible, request-time, router, SSR, browser, or controller behavior: read Root contract fallback and `diagnostics.md` for verification routing.',
         '- Bug fixes, regressions, incidents, broken public routes, auth/OAuth failures, integration failures, or production behavior fixes: read `DOCUMENTATION.md` before editing and update the relevant fix/regression docs when required.',
         '- Non-trivial feature, product, business-rule, UX, copy, or docs changes: read `DOCUMENTATION.md` before editing.',
-        '- Implementation edits: read `CODING_STYLE.md` before editing, plus the matching area file from the routing table.',
+        '- Implementation edits: read `CODING_STYLE.md` before editing, plus the matching area file from the routing table. While editing, record non-obvious decisions, workarounds, and constraints as why-comments per its `Decision and context comments` section.',
         '',
         '## Routing Table',
         '',