proteum 2.5.9 → 2.5.11

package/agents/project/diagnostics.md

@@ -18,7 +18,7 @@ This file is the canonical source of truth for diagnostics, temporary instrument
 
 - For long-lived dev reproductions, always request elevated permissions and run `npx proteum dev` outside the sandbox. Use an explicit task/thread-scoped session file, inspect `npx proteum runtime status` first, then use its exact next action so occupied router/HMR ports and untracked same-app runtimes are handled without page-body probes. After the server is ready, print the live server URL as a clickable Markdown link.
 - Use `--replace-existing` only when restarting the exact session file started by the current thread/task. Never replace another live session that belongs to a user, another thread, or an unknown owner.
-- Only the bare `npx proteum build` and bare `npx proteum dev` commands print the welcome banner and active Proteum installation method. Any extra argument or option skips the welcome banner. Terminal `npx proteum mcp` may print a compact central MCP ready banner when it starts or reuses the managed daemon. Only `npx proteum dev` clears the interactive terminal before rendering and reports connected app names plus successful connected `/ping` checks in the ready banner; keep that in mind when capturing or comparing command logs during diagnosis. Every `npx proteum dev` start ensures tracked instruction files contain the current managed `# Proteum Instructions` section and `CLAUDE.md` symlinks point to sibling `AGENTS.md` files before the dev loop begins.
+- When capturing or comparing command logs: only the bare `npx proteum build` and bare `npx proteum dev` commands print the welcome banner; any extra argument or option skips it. Only `npx proteum dev` clears the interactive terminal before rendering and reports connected app names plus successful connected `/ping` checks in its ready banner.
 - During `npx proteum dev`, the running app exposes the read-only Proteum MCP transport at `/__proteum/mcp`. Use it for runtime-adjacent agent reads instead of repeatedly spawning equivalent CLI diagnostics.
 - If machine MCP routing fails, run `npx proteum mcp status` and `npx proteum runtime status` from the intended app root. If no live session exists, use the exact MCP offline or runtime-status next action so occupied router/HMR ports are avoided. If the same app already responds on the configured port without live tracking, use or repair that runtime instead of starting another server. Do not `curl` normal page routes to identify which app owns a port; use runtime status or Proteum dev-only endpoints. If a live session exists but runtime/MCP is unreachable, stop the listed session file first, then start dev again. Do not start a second dev server in the same worktree, and do not start a second managed MCP daemon. Do not run diagnose, trace, or perf reads while runtime health is unreachable. Then retry MCP `workflow_start` and use the returned `projectId`.
 - For ownership or repo discovery questions, start with MCP `workflow_start`; use MCP `route_candidates { projectId, query }`, MCP `orient { projectId, query }`, and MCP `explain_summary { projectId, query }` only when the bootstrap owner summary is insufficient. Use `npx proteum orient <query>` or `npx proteum explain owner <query>` only when MCP is unavailable or terminal evidence is required.
@@ -34,7 +34,8 @@ This file is the canonical source of truth for diagnostics, temporary instrument
 - If existing traces are insufficient, arm `npx proteum trace arm --capture deep`, reproduce once, then inspect the new request with compact `npx proteum trace latest`; use `npx proteum trace show <requestId> --events` only when raw event detail is still required.
 - Use the browser MCP to inspect browser console errors and warnings for frontend, SSR, hydration, and controller-call issues.
 - Inspect server startup and runtime errors.
-- For protected browser or API flows in dev, prefer `npx proteum session <email> --role <role>` over driving the login UI, then use that session for browser MCP validation. Use `npx proteum e2e --session-email <email> --session-role <role>` only when Playwright end-to-end suites need the auth token through the child process environment. Use the login UI only when auth UX itself is under test.
+- Before every browser MCP validation pass in dev, create an admin session from the project instructions with `npx proteum session <admin-email> --role GOD` and use its `browserLoginUrl` or emitted cookie state before opening the target page. Skip this only when the task is explicitly testing auth, login, anonymous, or non-admin behavior; if no admin email is declared in the project instructions, stop and ask before browser validation.
+- For protected API flows in dev, prefer `npx proteum session <email> --role <role>` over driving the login UI, then use that session for browser MCP validation. Use `npx proteum e2e --session-email <email> --session-role <role>` only when Playwright end-to-end suites need the auth token through the child process environment. Use the login UI only when auth UX itself is under test.
 
 ## Temporary Instrumentation
 
@@ -55,16 +56,16 @@ This file is the canonical source of truth for diagnostics, temporary instrument
 ## Verification And Testing
 
 - Use the cheapest trustworthy verification that matches the failing layer.
-- After implementing a change, verify at the smallest trustworthy layer required by the changed surface first, including targeted tests when behavior changed. When the project defines `proteum.verify.config.ts`, prefer `npx proteum verify changed` for the first post-edit verification plan. Do not run coverage by default, and do not default to a running app, browser MCP, or Playwright while iterating when a narrower static or request-level verification is enough.
+- After implementing a change, verify at the smallest trustworthy layer required by the changed surface first, following the root contract `Verification Policy`. Do not default to a running app, browser MCP, or Playwright while iterating when a narrower static or request-level verification is enough.
 - For compile-time or type-safety issues, start with the relevant targeted typecheck or build command. Do not run them by default for unrelated runtime, copy, docs, or local refactor changes.
 - For request/runtime issues, verify through the real page, route, generated controller call, or command on a running app.
-- Start the smallest trustworthy runtime surface first: MCP `workflow_start`, then MCP `route_candidates { projectId, query }`, MCP `orient { projectId, query }`, or MCP `explain_summary { projectId, query }` only when more owner detail is needed. If runtime health is unreachable, repair/start dev before any diagnose, trace, or perf read. Once runtime is reachable, use the relevant real URL, generated controller call, command, or MCP `diagnose { projectId, path }`. Use CLI equivalents only when MCP is unavailable or terminal evidence is required. Use browser MCP validation only when request-level verification is insufficient or the change is browser-visible.
+- Start the smallest trustworthy runtime surface first: MCP `workflow_start`, then MCP `route_candidates { projectId, query }`, MCP `orient { projectId, query }`, or MCP `explain_summary { projectId, query }` only when more owner detail is needed. If runtime health is unreachable, repair/start dev before any diagnose, trace, or perf read. Once runtime is reachable, use the relevant real URL, generated controller call, command, or MCP `diagnose { projectId, path }`. Use CLI equivalents only when MCP is unavailable or terminal evidence is required. Use browser MCP validation when request-level verification is insufficient, when the change is browser-visible, or when the root `Verification Policy` requires the mandatory browser pass for a new UI-visible feature.
 - When automated browser assertions or suite coverage are required, use `npx proteum e2e --port <port>` for targeted or full Playwright suites. Do not use direct Playwright for browser validation outside the E2E wrapper, and do not launch raw browser automation against a shared persistent profile.
 - Focused verification should treat unrelated global diagnostics as visible but non-blocking by default. Use `--strict-global` only when the task explicitly requires broad clean-room validation.
 - For browser regressions, prefer a browser MCP repro first and add targeted Playwright E2E coverage only when the user asks for automated coverage, when a stable regression path needs automation, or when browser MCP verification is insufficient.
 - Only the final verifier agent should usually run browser flows. Earlier agents should stay on `orient`, `verify owner`, `verify request`, `diagnose`, and command-level checks unless browser execution is the only trustworthy reproducer.
 - Treat server startup failures, runtime errors, browser console errors or warnings, and Playwright failures as blocking unless they are clearly unrelated to the change.
-- When the touched surface can affect coding-style enforcement, run the targeted lint or typecheck command for that surface before finishing. 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. Run the full `npm run check` gate before pushing or when explicitly requested.
+- When the touched surface can affect coding-style enforcement, run the targeted lint or typecheck command for that surface before finishing. Commit-time and push-time gates follow the root contract `Verification Policy` and `Commit Workflow`.
 - If the task started any long-lived `proteum dev` server, stop it explicitly with `npx proteum dev stop --session-file <path>` or `npx proteum dev stop --all --stale`, then confirm the remaining tracked sessions with `npx proteum dev list --json`.
 - Add `data-testid` when stable selectors are missing instead of relying on brittle text or DOM-shape selectors.
 - If an isolated test misses prerequisite state, run the smallest broader scope that reproduces the real setup.

package/agents/project/optimizations.md

@@ -23,12 +23,7 @@ When tradeoffs exist inside optimization work, optimize in this order:
 
 ## SSR And Page Size
 
-- SSR page data belongs in the explicit `definePageRoute({ path, options, data, render })` `data` function, not in `api.fetch(...)`.
-- `options` carries route behavior. `data` returns one flat object or is `null` when the page has no SSR data loader.
-- Route-option keys and `_`-prefixed route-option aliases are forbidden in page data and must live in `options`.
-- If a page needs route data, return it from `data` and read it in `render`.
-- Controller fetchers and promises returned from `data` resolve before render.
-- Never use `api.fetch(...)` in page files for SSR loading.
+- The page `data` / `options` / `render` contract is defined in `client/pages/AGENTS.md`; SSR page data belongs in the route definition `data` function, never in `api.fetch(...)`.
 - Synchronous or SSR data calls must return only the strictly necessary data for the current render path to minimize SSR payload size.
 - If an existing controller or data method returns a broader shape than the SSR path needs, create a dedicated proxy controller method with a narrower typed contract instead of reusing the oversized payload.
 - Keep Prisma runtime access inside services when possible and prefer explicit `select` or narrow `include` in database queries.
@@ -46,4 +41,3 @@ When tradeoffs exist inside optimization work, optimize in this order:
 - For browser or SSR changes, use the browser MCP to load the real page, inspect the rendered HTML, and confirm the change does not ship unnecessary client code or oversized SSR payloads.
 - Treat clearly worse bundle size, runtime cost, or crawlable HTML quality as regressions to fix or justify explicitly, not as optional follow-up cleanup.
 - Build-only checks are supplementary.
-- For SSR changes, use the browser MCP to load the real page and inspect the rendered HTML plus browser console.

package/agents/project/server/services/AGENTS.md

@@ -29,9 +29,7 @@ Diagnostics source of truth: root-level `diagnostics.md`.
 - Use runtime models through `this.models` or the app model accessors.
 - Use Prisma typings through `@models/types` only.
 - In database queries, prefer explicit `select` or narrow `include`.
-- For database structure changes, edit the app's `schema.prisma` only. Never create or edit migration files manually.
-- Never use raw SQL DDL or other schema-mutating SQL to change database structure.
-- For read-only SQL diagnosis, use MCP `db_query` or `npx proteum db query "<sql>"`; only one capped `SELECT`, `SHOW`, or `EXPLAIN` statement is allowed.
+- For database structure changes, edit the app's `schema.prisma` only. Never create or edit migration files manually; the full database safety rules live in the root contract `Hard Stops`.
 - Prefer inferred return types such as `Awaited<ReturnType<MyService['methodName']>>` over manual DTO duplication.
 
 ## Errors

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/docs.ts

@@ -0,0 +1,223 @@
+import { UsageError } from 'clipanion';
+import fs from 'fs-extra';
+import path from 'path';
+
+import cli from '..';
+import { renderRows } from '../presentation/layout';
+import { renderStep, renderSuccess, renderTitle, renderWarning } from '../presentation/ink';
+
+const { collectDocAnchors } = require('../../docAnchors.js') as {
+    collectDocAnchors: (sourceText: string) => {
+        docs: string[];
+        fix: string[];
+        entries: { line: number; tag: string; value: string }[];
+    };
+};
+
+/*----------------------------------
+- TYPES
+----------------------------------*/
+
+type TDocsCheckFinding = {
+    detail: string;
+    kind: 'unresolved-anchor' | 'unanchored-fix-note' | 'orphan-feature-pack';
+    subject: string;
+};
+
+type TDocsCheckReport = {
+    anchoredFiles: number;
+    findings: TDocsCheckFinding[];
+    scannedFiles: number;
+};
+
+/*----------------------------------
+- HELPERS
+----------------------------------*/
+
+const skippedDirectories = new Set([
+    '.generated',
+    '.git',
+    '.proteum',
+    'bin',
+    'bin-dev',
+    'dist',
+    'node_modules',
+    'var',
+]);
+
+const isSourceFile = (name: string) => /\.(ts|tsx|mts|cts)$/.test(name);
+
+const walkSourceFiles = (directory: string, collected: string[] = []) => {
+    let entries: { isDirectory: () => boolean; name: string }[] = [];
+    try {
+        entries = fs.readdirSync(directory, { withFileTypes: true });
+    } catch (error) {
+        // An unreadable directory is not a documentation failure; skip it and
+        // keep scanning so one permission problem cannot mask real findings.
+        if (cli.verbose) console.warn(`docs check: skipping ${directory} (${(error as Error).message})`);
+        return collected;
+    }
+
+    entries.forEach((entry) => {
+        if (entry.name.startsWith('.') && entry.name !== '.') return;
+        const full = path.join(directory, entry.name);
+        if (entry.isDirectory()) {
+            if (skippedDirectories.has(entry.name)) return;
+            walkSourceFiles(full, collected);
+            return;
+        }
+        if (isSourceFile(entry.name)) collected.push(full);
+    });
+
+    return collected;
+};
+
+/**
+ * Resolve an anchor value the same way the `proteum/valid-doc-anchor` lint rule
+ * does: against every ancestor of the file that holds a `docs/` directory, so a
+ * monorepo app can point at the repository-level corpus.
+ */
+const resolveAnchorValue = (value: string, fromDirectory: string, root: string) => {
+    if (path.isAbsolute(value)) return fs.existsSync(value);
+
+    const roots: string[] = [];
+    let current = fromDirectory;
+    // The walk deliberately continues past `root`: running this from an app root
+    // inside a monorepo must still resolve anchors aimed at the repository-level
+    // corpus, exactly as the `proteum/valid-doc-anchor` lint rule does.
+    while (current) {
+        if (fs.existsSync(path.join(current, 'docs'))) roots.push(current);
+        const parent = path.dirname(current);
+        if (parent === current) break;
+        current = parent;
+    }
+    if (!roots.includes(root)) roots.push(root);
+
+    return roots.some((candidate) => fs.existsSync(path.resolve(candidate, value)));
+};
+
+const listFeaturePacks = (root: string) => {
+    const featuresDir = path.join(root, 'docs', 'features');
+    if (!fs.existsSync(featuresDir)) return [];
+
+    return fs
+        .readdirSync(featuresDir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name);
+};
+
+const listFixNotesRequiringAnchor = (root: string) => {
+    const fixesDir = path.join(root, 'docs', 'fixes');
+    if (!fs.existsSync(fixesDir)) return [];
+
+    return fs
+        .readdirSync(fixesDir)
+        .filter((name) => name.endsWith('.md'))
+        .filter((name) => /^## Agent warning\s*$/m.test(fs.readFileSync(path.join(fixesDir, name), 'utf8')));
+};
+
+export const buildDocsCheckReport = (root: string): TDocsCheckReport => {
+    const files = walkSourceFiles(root);
+    const findings: TDocsCheckFinding[] = [];
+    const referencedPacks = new Set<string>();
+    const referencedFixNotes = new Set<string>();
+    let anchoredFiles = 0;
+
+    files.forEach((filepath) => {
+        const anchors = collectDocAnchors(fs.readFileSync(filepath, 'utf8'));
+        if (anchors.entries.length === 0) return;
+
+        anchoredFiles += 1;
+        const relative = path.relative(root, filepath);
+
+        anchors.docs.forEach((value) => {
+            referencedPacks.add(path.basename(value.replace(/\/+$/, '')));
+            if (!resolveAnchorValue(value, path.dirname(filepath), root)) {
+                findings.push({ detail: `@docs ${value}`, kind: 'unresolved-anchor', subject: relative });
+            }
+        });
+
+        anchors.fix.forEach((value) => {
+            referencedFixNotes.add(path.basename(value));
+            if (!resolveAnchorValue(value, path.dirname(filepath), root)) {
+                findings.push({ detail: `@fix ${value}`, kind: 'unresolved-anchor', subject: relative });
+            }
+        });
+    });
+
+    listFixNotesRequiringAnchor(root).forEach((note) => {
+        if (referencedFixNotes.has(note)) return;
+        findings.push({
+            detail: 'carries an Agent warning that no source file anchors',
+            kind: 'unanchored-fix-note',
+            subject: `docs/fixes/${note}`,
+        });
+    });
+
+    listFeaturePacks(root).forEach((pack) => {
+        if (referencedPacks.has(pack)) return;
+        findings.push({
+            detail: 'no source file points at this pack with @docs',
+            kind: 'orphan-feature-pack',
+            subject: `docs/features/${pack}`,
+        });
+    });
+
+    return { anchoredFiles, findings, scannedFiles: files.length };
+};
+
+/*----------------------------------
+- COMMAND
+----------------------------------*/
+
+const renderFindings = (findings: TDocsCheckFinding[], kind: TDocsCheckFinding['kind'], label: string) => {
+    const matching = findings.filter((finding) => finding.kind === kind);
+    if (matching.length === 0) return `${label}: none`;
+
+    return [`${label}: ${matching.length}`, ...matching.map((finding) => `  ${finding.subject} | ${finding.detail}`)].join(
+        '\n',
+    );
+};
+
+export const run = async (): Promise<void> => {
+    if (cli.args.action !== 'check') throw new UsageError('Usage: `proteum docs check`');
+
+    const root = cli.paths.appRoot;
+
+    console.info(
+        [
+            await renderTitle('PROTEUM DOCS CHECK', 'Checking that code and documentation still point at each other.'),
+            renderRows([{ label: 'root', value: root === process.cwd() ? '.' : root }]),
+            await renderStep('[1/1]', 'Resolving doc anchors.'),
+        ].join('\n\n'),
+    );
+
+    const report = buildDocsCheckReport(root);
+    const unresolved = report.findings.filter((finding) => finding.kind === 'unresolved-anchor');
+
+    console.info(
+        [
+            renderRows([
+                { label: 'files scanned', value: String(report.scannedFiles) },
+                { label: 'files anchored', value: String(report.anchoredFiles) },
+            ]),
+            renderFindings(report.findings, 'unresolved-anchor', 'Unresolved anchors'),
+            renderFindings(report.findings, 'unanchored-fix-note', 'Fix notes with no code anchor'),
+            renderFindings(report.findings, 'orphan-feature-pack', 'Feature packs with no inbound anchor'),
+        ].join('\n\n'),
+    );
+
+    // Only a broken pointer fails the command. Missing coverage is reported as a
+    // backlog so a project can adopt anchors without a red build on day one.
+    if (unresolved.length > 0)
+        throw new Error(
+            `Proteum docs check failed: ${unresolved.length} doc anchor(s) do not resolve. Update or remove them.`,
+        );
+
+    const backlog = report.findings.length;
+    console.info(
+        backlog > 0
+            ? await renderWarning(`Anchors resolve. ${backlog} coverage gap(s) reported above.`)
+            : await renderSuccess('All doc anchors resolve, and coverage is complete.'),
+    );
+};

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;
+};