proteum 2.2.2-1 → 2.2.3

package/AGENTS.md

@@ -82,8 +82,8 @@ Do not stop at static analysis for routing, controllers, generated code, SSR, cl
 - When validating a concrete route, controller path, or failing page on a running dev server, prefer `proteum diagnose <path> --port <port>` first. Use raw `proteum trace ...` output when you need lower-level event detail beyond the diagnose summary.
 - When the issue is latency, CPU, SQL cost, render cost, or memory drift, inspect `proteum perf top`, `proteum perf request`, `proteum perf compare`, or `proteum perf memory` against the running dev server before adding custom instrumentation.
 - When a framework change can affect shipped client code size, run `proteum build --prod --analyze` for static bundle artifacts or `proteum build --prod --analyze --analyze-serve --analyze-port auto` when you need a local analyzer URL.
-- For protected browser or API flows in dev, prefer `npx proteum session <email> --role <role>` to mint a dev auth cookie instead of automating the login UI. Use the login UI only when login itself is the feature under test.
-- When a task needs browser execution instead of the higher-level verifier, prefer `npx proteum verify browser <path>` or direct Playwright with a disposable profile. Keep auth sourced from `npx proteum session`, not UI login or shared browser state.
+- For protected browser or API flows in dev, prefer `npx proteum session <email> --role <role>` or `npx proteum e2e --session-email <email> --session-role <role>` instead of automating the login UI. Use the login UI only when login itself is the feature under test.
+- When a task needs browser execution instead of the higher-level verifier, prefer `npx proteum verify browser <path>` or `npx proteum e2e --port <port>` for Playwright suites. Keep auth sourced from Proteum session helpers, not UI login or shared browser state.
 - For request-time behavior, arm traces with `proteum trace arm --capture deep`, reproduce once, then inspect `proteum trace latest` or `proteum trace show <requestId>`.
 - When the framework-facing workflow itself changed, verify the CLI surface too with `proteum verify framework-change --crosspath-port <port> --product-port <port> --website-port <port>`.
 - Only the final verifier agent should usually run browser flows. Other agents should stay on `orient`, `verify owner`, `verify request`, and command-level checks unless browser execution is the only trustworthy surface.

package/README.md

@@ -344,6 +344,7 @@ Proteum ships with a compact CLI focused on the real app lifecycle:
 | `proteum trace` | Inspect live dev-only request traces from the running SSR server |
 | `proteum command` | Run a dev-only internal command locally or against a running dev server |
 | `proteum session` | Mint a dev-only auth session token and Playwright-ready cookie payload |
+| `proteum e2e` | Run Playwright with Proteum-managed `E2E_*` values instead of shell-leading env assignments |
 | `proteum verify` | Validate framework-facing workflows across one or more running dev apps; `framework-change` is the built-in cross-reference-app check |
 | `proteum init` | Scaffold a new Proteum app with built-in deterministic templates |
 | `proteum configure agents` | Interactively configure Proteum-managed instruction symlinks and confirm overwrites for standalone or monorepo apps |
@@ -386,6 +387,7 @@ proteum command proteum/diagnostics/ping
 proteum command proteum/diagnostics/ping --port 3101
 proteum session admin@example.com --role ADMIN --port 3101
 proteum session god@example.com --role GOD --json
+proteum e2e --port 3101 --session-email admin@example.com --session-role ADMIN tests/e2e/features/admin.spec.ts
 proteum trace requests
 proteum trace arm --capture deep
 proteum trace latest
@@ -523,6 +525,7 @@ Proteum answers those questions with explicit artifacts:
 - the profiler `Explain`, `Doctor`, `Diagnose`, and `Perf` tabs for a human-readable view over the same diagnostics and trace-derived perf contracts
 - `proteum command ...` plus the profiler `Commands` tab for dev-only internal execution
 - `proteum session ...` for explicit authenticated dev browser or API bootstrapping without login UI automation
+- `proteum e2e ...` for Playwright runs that need `E2E_BASE_URL`, `E2E_PORT`, or `E2E_AUTH_TOKEN` without shell-leading env assignments
 
 If you are an LLM or automation agent, start here:
 
@@ -533,7 +536,7 @@ If you are an LLM or automation agent, start here:
 5. Inspect `server/controllers/**` for request entrypoints.
 6. Inspect `server/services/**` for business logic.
 7. Inspect `client/pages/**` for SSR routes and page data contracts.
-8. If the task touches a protected route or controller in dev and login UX is not the feature under test, use `proteum session <email> --role <role>` before Playwright or direct HTTP calls.
+8. If the task touches a protected route or controller in dev and login UX is not the feature under test, use `proteum e2e --session-email <email> --session-role <role>` for Playwright suites or `proteum session <email> --role <role>` before direct HTTP calls.
 
 For implementation rules in a real Proteum app, treat the local `AGENTS.md` files plus `proteum explain`, `proteum doctor`, `proteum diagnose`, `proteum perf`, and `proteum trace` as the task contract. This README is the framework overview, not the project-local instruction layer.
 

package/agents/project/AGENTS.md

@@ -56,7 +56,7 @@ Coding style source of truth: root-level `CODING_STYLE.md`.
 - When starting a long-lived dev server for an agent task, always request elevated permissions and run `npx proteum dev` outside the sandbox. Use an explicit task/thread-scoped session file such as `var/run/proteum/dev/agents/<task>.json`, inspect `npx proteum dev list --json` plus current listeners first, for example with `lsof -nP -iTCP -sTCP:LISTEN`, then choose a port that is not currently used before starting `npx proteum dev --session-file <path> --port <port>`. 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.
 - If the current app depends on local `file:` connected projects, boot every connected producer app too, each with its own task-scoped session file and free port, and run every one of those `proteum dev` processes with elevated permissions outside the sandbox before starting or verifying the consumer app.
-- For raw browser automation, use `npx proteum verify browser` when it matches the task, or direct Playwright with a disposable profile when lower-level control is required. Bootstrap protected browser state through `npx proteum session`.
+- For raw browser automation, use `npx proteum verify browser` when it matches the task, or `npx proteum e2e --port <port>` for targeted/full Playwright suites. Bootstrap protected browser state through `npx proteum e2e --session-email <email> --session-role <role>` or `npx proteum session`.
 - Current CLI banner contract: only the bare `proteum build` and bare `proteum dev` commands print the welcome banner and include the active Proteum installation method. Any extra argument or option skips the banner. Only `proteum dev` clears the interactive terminal before rendering, exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys in its session UI, and reports connected app names plus successful connected `/ping` checks in the ready banner. When the app root is missing `AGENTS.md`, the bare interactive `proteum dev` start offers to launch `proteum configure agents` before the dev loop begins.
 
 ### Before Finishing
@@ -179,8 +179,8 @@ Verify at the correct layer:
 - Router or plugin changes: verify request context, auth, redirects, metrics, and validation on a running app.
 - New features or feature-behavior changes: use the cheapest trustworthy verification while iterating, then update the relevant end-to-end coverage and finish by running the full Playwright suite.
 - Generated, connected, or ownership-ambiguous changes: start with `npx proteum orient <query>` and prefer `npx proteum verify owner <query>` before broad global checks.
-- Browser-visible issues: prefer `npx proteum verify browser <path>` or the narrowest targeted Playwright pass only after request-level verification is insufficient.
-- Raw browser execution beyond `npx proteum verify browser`: use direct Playwright with a disposable profile, and keep that step for the final verifier agent unless a narrower surface cannot reproduce the issue.
+- Browser-visible issues: prefer `npx proteum verify browser <path>` or the narrowest `npx proteum e2e --port <port> ...` Playwright pass only after request-level verification is insufficient.
+- Raw browser execution beyond `npx proteum verify browser`: use `npx proteum e2e --port <port>` first, then direct Playwright with a disposable profile only when the wrapper cannot express the needed control. Keep that step for the final verifier agent unless a narrower surface cannot reproduce the issue.
 - For trace-first reproduction, session-based auth setup, temporary logs, and post-fix surface checks, follow root-level `diagnostics.md`.
 
 ## Implementation Rules

package/agents/project/diagnostics.md

@@ -17,7 +17,7 @@ This file is the canonical source of truth for diagnostics, temporary instrument
 - 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 banner. 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. When the app root is missing `AGENTS.md`, the bare interactive `npx proteum dev` start offers to launch `npx proteum configure agents` before the dev loop begins.
 - For ownership or repo discovery questions, start with `npx proteum orient <query>` instead of jumping straight into source searches.
 - For request-time issues in dev, start with `npx proteum diagnose <path> --port <port>` when you have a concrete failing route, page, controller path, or request target. It combines owner lookup, manifest diagnostics, contract diagnostics, matching trace data, and buffered server logs in one pass.
-- Prefer focused verification before global checks: `npx proteum verify owner <query>`, `npx proteum verify request <path>`, and only then `npx proteum verify browser <path>` or targeted Playwright when the bug is browser-visible.
+- Prefer focused verification before global checks: `npx proteum verify owner <query>`, `npx proteum verify request <path>`, and only then `npx proteum verify browser <path>` or `npx proteum e2e --port <port> ...` when the bug is browser-visible.
 - When diagnosing a consumer app that depends on local `file:` connected projects, boot every connected producer app too, each on its own free port and task-scoped session file, and run every one of those `proteum dev` processes with elevated permissions outside the sandbox before reproducing the consumer issue.
 - For connected-project failures, confirm the consumer app resolves the expected `connect.<Namespace>.source` and `connect.<Namespace>.urlInternal` values, the producer app exposes `GET /api/__proteum/connected/ping`, and the imported controller entries show `scope=connected` in `proteum explain`.
 - Use `npx proteum explain owner <query>` when you need a fast ownership graph for a route, controller path, source file, or generated artifact before reading code.
@@ -28,7 +28,7 @@ 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 `npx proteum trace latest` or `npx proteum trace show <requestId>`.
 - 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. Feed that auth into `npx proteum verify browser ...` or direct Playwright. Use the login UI only when auth UX itself is under test.
+- For protected browser or API flows in dev, prefer `npx proteum session <email> --role <role>` over driving the login UI. Feed that auth into `npx proteum verify browser ...`, or use `npx proteum e2e --session-email <email> --session-role <role>` so Playwright receives the auth token through the child process environment. Use the login UI only when auth UX itself is under test.
 
 ## Temporary Instrumentation
 
@@ -53,7 +53,7 @@ This file is the canonical source of truth for diagnostics, temporary instrument
 - 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: `npx proteum orient <query>`, then the relevant real URL, generated controller call, command, or `npx proteum diagnose <path> --port <port>`. Add targeted Playwright coverage only when request-level verification is insufficient or the change is browser-visible.
-- Proteum does not provide a dedicated raw browser-runtime CLI. When `npx proteum verify browser` is insufficient, use direct Playwright with a disposable profile. Do not launch raw browser automation against a shared persistent profile.
+- When `npx proteum verify browser` is insufficient, use `npx proteum e2e --port <port>` for targeted or full Playwright suites. Use direct Playwright with a disposable profile only when the wrapper cannot express the needed browser control. 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 real browser repro first and add targeted Playwright coverage only when the user asks for automated coverage, when a stable regression path needs automation, or when manual/browser 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.

package/agents/project/root/AGENTS.md

@@ -46,7 +46,7 @@ Coding style source of truth: root-level `CODING_STYLE.md`.
 - When starting a long-lived dev server for an agent task, always request elevated permissions and run `npx proteum dev` outside the sandbox. Use an explicit task/thread-scoped session file such as `var/run/proteum/dev/agents/<task>.json`, inspect `npx proteum dev list --json` plus current listeners first, for example with `lsof -nP -iTCP -sTCP:LISTEN`, then choose a port that is not currently used before starting `npx proteum dev --session-file <path> --port <port>`. 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.
 - If the current app depends on local `file:` connected projects, boot every connected producer app too, each with its own task-scoped session file and free port, and run every one of those `proteum dev` processes with elevated permissions outside the sandbox before starting or verifying the consumer app.
-- For raw browser automation, use `npx proteum verify browser` when it matches the task, or direct Playwright with a disposable profile when lower-level control is required. Bootstrap protected browser state through `npx proteum session`.
+- For raw browser automation, use `npx proteum verify browser` when it matches the task, or `npx proteum e2e --port <port>` for targeted/full Playwright suites. Bootstrap protected browser state through `npx proteum e2e --session-email <email> --session-role <role>` or `npx proteum session`.
 - Current CLI banner contract: only the bare `proteum build` and bare `proteum dev` commands print the welcome banner and include the active Proteum installation method. Any extra argument or option skips the banner. Only `proteum dev` clears the interactive terminal before rendering, exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys in its session UI, and reports connected app names plus successful connected `/ping` checks in the ready banner. When the app root is missing `AGENTS.md`, the bare interactive `proteum dev` start offers to launch `proteum configure agents` before the dev loop begins.
 
 ### Before Finishing
@@ -169,8 +169,8 @@ Verify at the correct layer:
 - Router or plugin changes: verify request context, auth, redirects, metrics, and validation on a running app.
 - New features or feature-behavior changes: use the cheapest trustworthy verification while iterating, then update the relevant end-to-end coverage and finish by running the full Playwright suite.
 - Generated, connected, or ownership-ambiguous changes: start with `npx proteum orient <query>` and prefer `npx proteum verify owner <query>` before broad global checks.
-- Browser-visible issues: prefer `npx proteum verify browser <path>` or the narrowest targeted Playwright pass only after request-level verification is insufficient.
-- Raw browser execution beyond `npx proteum verify browser`: use direct Playwright with a disposable profile, and keep that step for the final verifier agent unless a narrower surface cannot reproduce the issue.
+- Browser-visible issues: prefer `npx proteum verify browser <path>` or the narrowest `npx proteum e2e --port <port> ...` Playwright pass only after request-level verification is insufficient.
+- Raw browser execution beyond `npx proteum verify browser`: use `npx proteum e2e --port <port>` first, then direct Playwright with a disposable profile only when the wrapper cannot express the needed control. Keep that step for the final verifier agent unless a narrower surface cannot reproduce the issue.
 - For trace-first reproduction, session-based auth setup, temporary logs, and post-fix surface checks, follow root-level `diagnostics.md`.
 
 ## Implementation Rules

package/agents/project/tests/AGENTS.md

@@ -10,7 +10,7 @@ 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.
 - 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. Use a real browser 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 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 real browser repro against a running app during iteration when it is the fastest trustworthy loop.
 - 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.
@@ -22,4 +22,4 @@ 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 session <email> --role <role>` over automating login unless the login flow itself is under test.
+- 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.

package/cli/app/index.ts

@@ -36,6 +36,12 @@ const parseRouterPortOverride = (rawPort: string | boolean | string[] | undefine
 
 const normalizeModulePath = (value: string) => value.replace(/\\/g, '/').replace(/\/$/, '');
 
+const resolveSideTsconfig = (appRoot: string, side: TAppSide) => {
+    const candidates = [path.join(appRoot, side, 'tsconfig.json'), path.join(appRoot, side, 'app.tsconfig.json')];
+
+    return candidates.find((candidate) => fs.existsSync(candidate));
+};
+
 const resolveTranspileModuleDirectories = ({
     moduleNames,
     resolvePackageRoot,
@@ -183,17 +189,21 @@ export class App {
     ----------------------------------*/
 
     public aliases = {
-        client: new TsAlias({
-            rootDir: this.paths.root + '/client',
-            modulesDir: [cli.paths.framework.appNodeModulesRoot, cli.paths.framework.frameworkNodeModulesRoot],
-            debug: false,
-        }),
-        server: new TsAlias({
-            rootDir: this.paths.root + '/server',
+        client: this.createSideAliases('client'),
+        server: this.createSideAliases('server'),
+    };
+
+    private createSideAliases(side: TAppSide) {
+        const tsconfigFilepath = resolveSideTsconfig(this.paths.root, side);
+
+        if (!tsconfigFilepath) return new TsAlias({ aliases: [] });
+
+        return new TsAlias({
+            rootDir: tsconfigFilepath,
             modulesDir: [cli.paths.framework.appNodeModulesRoot, cli.paths.framework.frameworkNodeModulesRoot],
             debug: false,
-        }),
-    };
+        });
+    }
 
     private loadPkg() {
         return fs.readJSONSync(this.paths.root + '/package.json');

package/cli/commands/check.ts

@@ -1,5 +1,5 @@
 import cli from '..';
-import { refreshGeneratedTypings, runAppLint, runAppTypecheck } from '../utils/check';
+import { hasAppConfig, refreshGeneratedTypings, runAppLint, runAppTypecheck } from '../utils/check';
 import { renderRows } from '../presentation/layout';
 import { renderStep, renderSuccess, renderTitle } from '../presentation/ink';
 
@@ -23,8 +23,12 @@ export const run = async (): Promise<void> => {
             renderRows([{ label: 'app', value: cli.paths.appRoot === process.cwd() ? '.' : cli.paths.appRoot }]),
         ].join('\n\n'),
     );
-    console.info(await renderStep('[1/3]', 'Refreshing generated typings.'));
-    await refreshGeneratedTypings();
+    if (hasAppConfig()) {
+        console.info(await renderStep('[1/3]', 'Refreshing generated typings.'));
+        await refreshGeneratedTypings();
+    } else {
+        console.info(await renderStep('[1/3]', 'Skipping generated typings: no Proteum app config found.'));
+    }
     console.info(await renderStep('[2/3]', 'Running TypeScript typechecking.'));
     await runAppTypecheck();
     console.info(await renderStep('[3/3]', 'Running ESLint.'));

package/cli/commands/configure.ts

@@ -13,7 +13,7 @@ import cli from '..';
 import { renderRows } from '../presentation/layout';
 import { isLikelyProteumAppRoot } from '../presentation/commands';
 import { renderStep, renderSuccess, renderTitle, renderWarning } from '../presentation/ink';
-import { configureProjectAgentSymlinks, type TConfigureProjectAgentSymlinksResult } from '../utils/agents';
+import { configureProjectAgentInstructions, type TConfigureProjectAgentInstructionsResult } from '../utils/agents';
 
 /*----------------------------------
 - HELPERS
@@ -93,7 +93,12 @@ const promptBlockedOverwritePaths = async (blockedPaths: string[]) => {
     if (blockedPaths.length === 0) return [];
 
     console.info(await renderWarning('Proteum found existing non-managed instruction paths.'));
-    console.info(['Choose whether to overwrite each path with a Proteum-managed symlink:', ...blockedPaths.map((entry) => `- ${entry}`)].join('\n'));
+    console.info(
+        [
+            'Choose whether to overwrite each path with a Proteum-managed instruction stub:',
+            ...blockedPaths.map((entry) => `- ${entry}`),
+        ].join('\n'),
+    );
 
     const overwriteBlockedPaths: string[] = [];
 
@@ -118,7 +123,7 @@ const promptBlockedOverwritePaths = async (blockedPaths: string[]) => {
     return overwriteBlockedPaths;
 };
 
-const renderConfigureResultSections = (result: TConfigureProjectAgentSymlinksResult) => {
+const renderConfigureResultSections = (result: TConfigureProjectAgentInstructionsResult) => {
     const sections: string[] = [];
 
     sections.push(
@@ -178,7 +183,7 @@ export const runConfigureAgentsWizard = async ({
             : undefined;
     console.info(
         [
-            await renderTitle('PROTEUM CONFIGURE AGENTS', 'Configure Proteum-managed instruction symlinks.'),
+            await renderTitle('PROTEUM CONFIGURE AGENTS', 'Configure Proteum-managed instruction stubs.'),
             renderRows([{ label: 'app', value: appRoot === process.cwd() ? '.' : appRoot }]),
         ].join('\n\n'),
     );
@@ -204,7 +209,7 @@ export const runConfigureAgentsWizard = async ({
           })
         : undefined;
 
-    const preview = configureProjectAgentSymlinks({
+    const preview = configureProjectAgentInstructions({
         appRoot,
         coreRoot,
         dryRun: true,
@@ -216,12 +221,12 @@ export const runConfigureAgentsWizard = async ({
         await renderStep(
             '[1/1]',
             isMonorepo
-                ? `Writing monorepo-aware instruction symlinks using ${monorepoRoot}.`
-                : 'Writing standalone instruction symlinks.',
+                ? `Writing monorepo-aware instruction stubs using ${monorepoRoot}.`
+                : 'Writing standalone instruction stubs.',
         ),
     );
 
-    const result = configureProjectAgentSymlinks({
+    const result = configureProjectAgentInstructions({
         appRoot,
         coreRoot,
         monorepoRoot,
@@ -229,7 +234,7 @@ export const runConfigureAgentsWizard = async ({
     });
     const sections = renderConfigureResultSections(result);
 
-    console.info(await renderSuccess('Proteum-managed instruction symlinks are configured.'));
+    console.info(await renderSuccess('Proteum-managed instruction stubs are configured.'));
 
     if (sections.length > 0) console.info(`\n${sections.join('\n\n')}`);
 };

package/cli/commands/e2e.ts

@@ -0,0 +1,204 @@
+import { spawn } from 'child_process';
+import dotenv from 'dotenv';
+import fs from 'fs-extra';
+import got from 'got';
+import path from 'path';
+import { UsageError } from 'clipanion';
+
+import cli from '..';
+import type { TDevSessionErrorResponse, TDevSessionStartResponse } from '../../common/dev/session';
+
+type TPlaywrightInvocation = {
+    command: string;
+    args: string[];
+};
+
+const normalizeBaseUrl = (value: string) => value.replace(/\/+$/, '');
+
+const getRouterPortFromManifest = () => {
+    const manifestFilepath = path.join(cli.args.workdir as string, '.proteum', 'manifest.json');
+    if (!fs.existsSync(manifestFilepath)) return undefined;
+
+    const manifest = fs.readJsonSync(manifestFilepath, { throws: false }) as
+        | { env?: { resolved?: { routerPort?: number } } }
+        | undefined;
+    const port = manifest?.env?.resolved?.routerPort;
+
+    if (typeof port !== 'number' || port <= 0) return undefined;
+
+    return String(port);
+};
+
+const getRouterPort = () => {
+    const overridePort = typeof cli.args.port === 'string' && cli.args.port ? cli.args.port : '';
+    if (overridePort) return overridePort;
+
+    const manifestPort = getRouterPortFromManifest();
+    if (manifestPort) return manifestPort;
+
+    return '';
+};
+
+const getBaseUrlCandidates = () => {
+    const explicitUrl = typeof cli.args.url === 'string' && cli.args.url ? cli.args.url.trim() : '';
+    if (explicitUrl) return [normalizeBaseUrl(explicitUrl)];
+
+    const port = getRouterPort();
+    if (!port) return [];
+
+    return [...new Set([`http://localhost:${port}`, `http://127.0.0.1:${port}`, `http://[::1]:${port}`])];
+};
+
+const getSessionErrorMessage = (body: TDevSessionErrorResponse | object | string | undefined, statusCode: number) => {
+    if (typeof body === 'object' && body !== null && 'error' in body && typeof body.error === 'string') {
+        return body.error;
+    }
+
+    return `Session request failed with status ${statusCode}.`;
+};
+
+const hasStructuredSessionError = (body: TDevSessionErrorResponse | object | string | undefined): body is TDevSessionErrorResponse =>
+    typeof body === 'object' && body !== null && 'error' in body && typeof body.error === 'string';
+
+const requestSession = async ({ email, role }: { email: string; role: string }) => {
+    const attempts: string[] = [];
+
+    for (const baseUrl of getBaseUrlCandidates()) {
+        try {
+            const response = await got(`${baseUrl}/__proteum/session/start`, {
+                method: 'POST',
+                json: role ? { email, role } : { email },
+                responseType: 'json',
+                throwHttpErrors: false,
+                retry: { limit: 0 },
+            });
+
+            if (response.statusCode >= 400) {
+                if (response.statusCode === 404 && !hasStructuredSessionError(response.body as TDevSessionErrorResponse | object | string | undefined)) {
+                    attempts.push(`${baseUrl}/__proteum/session/start: returned 404`);
+                    continue;
+                }
+
+                throw new UsageError(
+                    getSessionErrorMessage(response.body as TDevSessionErrorResponse | object | string | undefined, response.statusCode),
+                );
+            }
+
+            return {
+                baseUrl,
+                token: (response.body as TDevSessionStartResponse).session.token,
+            };
+        } catch (error) {
+            if (error instanceof UsageError) throw error;
+
+            const message = error instanceof Error ? error.message : String(error);
+            attempts.push(`${baseUrl}/__proteum/session/start: ${message}`);
+        }
+    }
+
+    throw new UsageError(
+        [
+            'Could not reach the Proteum session server.',
+            ...attempts.map((attempt) => `- ${attempt}`),
+            'Start the app with `proteum dev`, then pass --port or --url to `proteum e2e`.',
+        ].join('\n'),
+    );
+};
+
+const resolveBaseUrl = (sessionBaseUrl?: string) => {
+    if (sessionBaseUrl) return sessionBaseUrl;
+
+    const [baseUrl] = getBaseUrlCandidates();
+    if (baseUrl) return baseUrl;
+
+    throw new UsageError('Could not determine E2E_BASE_URL. Pass --port or --url to `proteum e2e`.');
+};
+
+const parseEnvPair = (value: string) => {
+    const separatorIndex = value.indexOf('=');
+    if (separatorIndex <= 0) {
+        throw new UsageError(`Invalid --env value "${value}". Expected KEY=value.`);
+    }
+
+    const key = value.slice(0, separatorIndex).trim();
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+        throw new UsageError(`Invalid --env key "${key}".`);
+    }
+
+    return { key, value: value.slice(separatorIndex + 1) };
+};
+
+const readEnvFiles = (filepaths: string[]) => {
+    const env: Record<string, string> = {};
+
+    for (const filepath of filepaths) {
+        const absoluteFilepath = path.resolve(cli.args.workdir as string, filepath);
+
+        if (!fs.existsSync(absoluteFilepath)) {
+            throw new UsageError(`Env file does not exist: ${absoluteFilepath}`);
+        }
+
+        Object.assign(env, dotenv.parse(fs.readFileSync(absoluteFilepath)));
+    }
+
+    return env;
+};
+
+const resolvePlaywrightInvocation = (appRoot: string): TPlaywrightInvocation => {
+    const binaryName = process.platform === 'win32' ? 'playwright.cmd' : 'playwright';
+    const localBinary = path.join(appRoot, 'node_modules', '.bin', binaryName);
+
+    if (fs.existsSync(localBinary)) {
+        return { command: localBinary, args: ['test'] };
+    }
+
+    return { command: 'npx', args: ['playwright', 'test'] };
+};
+
+const runPlaywright = async ({ env, playwrightArgs }: { env: Record<string, string>; playwrightArgs: string[] }) => {
+    const appRoot = cli.args.workdir as string;
+    const invocation = resolvePlaywrightInvocation(appRoot);
+
+    return await new Promise<number | null>((resolve, reject) => {
+        const child = spawn(invocation.command, [...invocation.args, ...playwrightArgs], {
+            cwd: appRoot,
+            env: {
+                ...process.env,
+                ...env,
+            },
+            stdio: 'inherit',
+        });
+
+        child.once('error', reject);
+        child.once('close', (exitCode) => resolve(exitCode));
+    });
+};
+
+export const run = async () => {
+    const sessionEmail = typeof cli.args.sessionEmail === 'string' ? cli.args.sessionEmail.trim() : '';
+    const sessionRole = typeof cli.args.sessionRole === 'string' ? cli.args.sessionRole.trim() : '';
+    const envFilepaths = Array.isArray(cli.args.envFile) ? cli.args.envFile : [];
+    const envPairs = Array.isArray(cli.args.env) ? cli.args.env : [];
+    const playwrightArgs = Array.isArray(cli.args.playwrightArgs) ? cli.args.playwrightArgs : [];
+    const explicitPort = getRouterPort();
+
+    const explicitEnv = readEnvFiles(envFilepaths);
+    for (const pair of envPairs) {
+        const parsed = parseEnvPair(pair);
+        explicitEnv[parsed.key] = parsed.value;
+    }
+
+    const session = sessionEmail ? await requestSession({ email: sessionEmail, role: sessionRole }) : undefined;
+    const baseUrl = resolveBaseUrl(session?.baseUrl);
+    const exitCode = await runPlaywright({
+        env: {
+            ...explicitEnv,
+            E2E_BASE_URL: baseUrl,
+            ...(explicitPort ? { E2E_PORT: explicitPort } : {}),
+            ...(session?.token ? { E2E_AUTH_TOKEN: session.token } : {}),
+        },
+        playwrightArgs,
+    });
+
+    return exitCode ?? 1;
+};

package/cli/commands/typecheck.ts

@@ -1,5 +1,5 @@
 import cli from '..';
-import { refreshGeneratedTypings, runAppTypecheck } from '../utils/check';
+import { hasAppConfig, refreshGeneratedTypings, runAppTypecheck } from '../utils/check';
 import { renderRows } from '../presentation/layout';
 import { renderStep, renderSuccess, renderTitle } from '../presentation/ink';
 
@@ -23,8 +23,12 @@ export const run = async (): Promise<void> => {
             renderRows([{ label: 'app', value: cli.paths.appRoot === process.cwd() ? '.' : cli.paths.appRoot }]),
         ].join('\n\n'),
     );
-    console.info(await renderStep('[1/2]', 'Refreshing generated typings.'));
-    await refreshGeneratedTypings();
+    if (hasAppConfig()) {
+        console.info(await renderStep('[1/2]', 'Refreshing generated typings.'));
+        await refreshGeneratedTypings();
+    } else {
+        console.info(await renderStep('[1/2]', 'Skipping generated typings: no Proteum app config found.'));
+    }
     console.info(await renderStep('[2/2]', 'Running TypeScript typechecking.'));
     await runAppTypecheck();
     console.info(await renderSuccess('Typecheck passed.'));

package/cli/presentation/commands.ts

@@ -14,6 +14,7 @@ export const proteumCommandNames = [
     'typecheck',
     'lint',
     'check',
+    'e2e',
     'connect',
     'doctor',
     'explain',
@@ -55,7 +56,7 @@ export const proteumRecommendedFlow: TRow[] = [
 
 export const proteumCommandGroups: Array<{ title: string; names: TProteumCommandName[] }> = [
     { title: 'Daily workflow', names: ['dev', 'refresh', 'build'] },
-    { title: 'Quality gates', names: ['typecheck', 'lint', 'check'] },
+    { title: 'Quality gates', names: ['typecheck', 'lint', 'check', 'e2e'] },
     { title: 'Manifest and contracts', names: ['connect', 'doctor', 'explain', 'orient', 'diagnose', 'perf', 'trace', 'command', 'session', 'verify'] },
     { title: 'Project scaffolding', names: ['init', 'configure', 'create', 'migrate'] },
 ];
@@ -112,22 +113,22 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
     configure: {
         name: 'configure',
         category: 'Project scaffolding',
-        summary: 'Interactively configure Proteum-managed instruction symlinks for a standalone app or monorepo app root.',
+        summary: 'Interactively configure Proteum-managed instruction stubs for a standalone app or monorepo app root.',
         usage: 'proteum configure agents',
         bestFor:
-            'Creating or switching the managed `AGENTS.md` instruction layout intentionally instead of having `init` or `dev` write symlinks implicitly.',
+            'Creating or switching the managed `AGENTS.md` instruction layout intentionally instead of having `init` or `dev` write instruction files implicitly.',
         examples: [
             {
-                description: 'Configure instruction symlinks for the current standalone app',
+                description: 'Configure instruction stubs for the current standalone app',
                 command: 'proteum configure agents',
             },
         ],
         notes: [
-            'This command is interactive. It asks whether the current Proteum app belongs to a monorepo and, if so, which ancestor path should receive the reusable root `AGENTS.md` symlink.',
+            'This command is interactive. It asks whether the current Proteum app belongs to a monorepo and, if so, which ancestor path should receive the reusable root `AGENTS.md` stub.',
             'Standalone mode writes the full app-root instruction set into the current Proteum app root.',
             'Monorepo mode writes the reusable root `AGENTS.md` into the chosen monorepo root and switches the current app root `AGENTS.md` to the app-root addendum.',
-            'If a target path already contains a non-managed file or foreign symlink, the interactive flow asks whether to overwrite it with the Proteum-managed symlink.',
-            'Declined non-managed paths are left untouched; Proteum still creates missing symlinks and updates symlinks it already manages.',
+            'If a target path already contains a non-managed file or foreign symlink, the interactive flow asks whether to overwrite it with the Proteum-managed stub.',
+            'Declined non-managed paths are left untouched; Proteum still creates missing stubs and updates stubs or symlinks it already manages.',
         ],
         status: 'experimental',
     },
@@ -276,6 +277,35 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         notes: ['This command executes refresh, typecheck, then lint in that order.'],
         status: 'stable',
     },
+    e2e: {
+        name: 'e2e',
+        category: 'Quality gates',
+        summary: 'Run app Playwright tests with Proteum-managed E2E environment values.',
+        usage:
+            'proteum e2e [--cwd <path>] [--port <port>|--url <url>] [--session-email <email>] [--session-role <role>] [--env KEY=value] [--env-file <path>] [--grep <text>] [--project <name>] [specs...]',
+        bestFor:
+            'Running targeted or full Playwright suites without shell-leading environment assignments for base URLs, auth tokens, or per-run values.',
+        examples: [
+            {
+                description: 'Run the full suite against a local dev server',
+                command: 'proteum e2e --port 3101',
+            },
+            {
+                description: 'Run one spec with a dev auth token minted internally',
+                command: 'proteum e2e --port 3101 --session-email admin@example.com --session-role ADMIN tests/e2e/features/admin.spec.ts',
+            },
+            {
+                description: 'Load extra dotenv values before Playwright starts',
+                command: 'proteum e2e --url http://localhost:3101 --env-file .proteum/e2e.env --grep smoke',
+            },
+        ],
+        notes: [
+            '`proteum e2e` spawns Playwright with `E2E_BASE_URL`, optional `E2E_PORT`, optional `E2E_AUTH_TOKEN`, and any `--env`/`--env-file` values in the child process environment.',
+            'Common Playwright flags are exposed directly: `--config`, `--debug`, `--grep`, `--headed`, `--list`, `--project`, `--reporter`, `--retries`, `--timeout`, `--ui`, and `--workers`.',
+            'The shell command itself stays `proteum e2e ...`, so Codex does not need to run `FOO=bar npx playwright test ...`.',
+        ],
+        status: 'experimental',
+    },
     connect: {
         name: 'connect',
         category: 'Manifest and contracts',

package/cli/runtime/command.ts

@@ -4,11 +4,11 @@ import cli, { type TArgsObject } from '../context';
 import { createClipanionUsage, proteumCommands, type TProteumCommandName } from '../presentation/commands';
 import { createArgs } from './argv';
 
-type TRunModule = { run: () => Promise<void> };
+type TRunModule = { run: () => Promise<number | void> };
 
 export const runCommandModule = async (loader: () => Promise<TRunModule>) => {
     const module = await loader();
-    await module.run();
+    return await module.run();
 };
 
 export abstract class ProteumCommand extends Command {