proteum 2.1.9 → 2.2.0

package/cli/presentation/commands.ts

@@ -6,6 +6,8 @@ import type { TRow } from './layout';
 export const proteumCommandNames = [
     'init',
     'create',
+    'configure',
+    'migrate',
     'dev',
     'refresh',
     'build',
@@ -15,6 +17,7 @@ export const proteumCommandNames = [
     'connect',
     'doctor',
     'explain',
+    'orient',
     'diagnose',
     'perf',
     'trace',
@@ -44,17 +47,17 @@ export type TProteumCommandDoc = {
 };
 
 export const proteumRecommendedFlow: TRow[] = [
-    { label: '1. proteum dev', value: 'Start the compiler, SSR server, and hot reload loop.' },
-    { label: '2. proteum refresh', value: 'Regenerate .proteum contracts and typings after source or framework changes.' },
-    { label: '3. proteum check', value: 'Refresh, typecheck, and lint before you commit or push.' },
-    { label: '4. proteum build --prod', value: 'Produce the production server and client bundles.' },
+    { label: '1. proteum orient <query>', value: 'Start here for multi-repo, generated, or connected work before reading code.' },
+    { label: '2. proteum dev', value: 'Start the compiler, SSR server, and hot reload loop.' },
+    { label: '3. proteum diagnose <path> --hit <path>', value: 'Validate the smallest trustworthy request surface before broader checks.' },
+    { label: '4. proteum check', value: 'Refresh, typecheck, and lint before you commit or push.' },
 ];
 
 export const proteumCommandGroups: Array<{ title: string; names: TProteumCommandName[] }> = [
     { title: 'Daily workflow', names: ['dev', 'refresh', 'build'] },
     { title: 'Quality gates', names: ['typecheck', 'lint', 'check'] },
-    { title: 'Manifest and contracts', names: ['connect', 'doctor', 'explain', 'diagnose', 'perf', 'trace', 'command', 'session', 'verify'] },
-    { title: 'Project scaffolding', names: ['init', 'create'] },
+    { title: 'Manifest and contracts', names: ['connect', 'doctor', 'explain', 'orient', 'diagnose', 'perf', 'trace', 'command', 'session', 'verify'] },
+    { title: 'Project scaffolding', names: ['init', 'configure', 'create', 'migrate'] },
 ];
 
 export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> = {
@@ -106,15 +109,66 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         ],
         status: 'experimental',
     },
+    configure: {
+        name: 'configure',
+        category: 'Project scaffolding',
+        summary: 'Interactively configure Proteum-managed instruction symlinks 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.',
+        examples: [
+            {
+                description: 'Configure instruction symlinks 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.',
+            '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.',
+        ],
+        status: 'experimental',
+    },
+    migrate: {
+        name: 'migrate',
+        category: 'Project scaffolding',
+        summary: 'Rewrite legacy page registrations to the explicit Router.page(path, options, data, render) contract.',
+        usage: 'proteum migrate page-contract [--cwd <path>] [--dry-run] [--json]',
+        bestFor:
+            'Upgrading existing Proteum apps to the single explicit page contract without hand-editing every `client/pages/**` file.',
+        examples: [
+            { description: 'Rewrite the current app in place', command: 'proteum migrate page-contract' },
+            {
+                description: 'Preview the migration without writing files',
+                command: 'proteum migrate page-contract --dry-run --json',
+            },
+            {
+                description: 'Migrate another app root from the current shell',
+                command: 'proteum migrate page-contract --cwd /path/to/app',
+            },
+        ],
+        notes: [
+            'This migration rewrites supported legacy Router.page signatures to the explicit 4-argument form.',
+            'If a page data function cannot be analyzed safely, Proteum leaves the file unchanged and reports a manual-fix location.',
+            'Run `proteum typecheck` and `proteum build --strict` after the rewrite.',
+        ],
+        status: 'experimental',
+    },
     dev: {
         name: 'dev',
         category: 'Daily workflow',
         summary: 'Start the local compiler, SSR server, and hot reload loop.',
-        usage: 'proteum dev [list|stop] [--port <port>] [--session-file <path>] [--replace-existing] [--all] [--stale] [--json] [--cache|--no-cache]',
+        usage: 'proteum dev [list|stop] [--cwd <path>] [--port <port>] [--session-file <path>] [--replace-existing] [--all] [--stale] [--json] [--cache|--no-cache]',
         bestFor:
             'Day-to-day app work. This is the main entrypoint used by the current reference apps during local development.',
         examples: [
             { description: 'Start the app on its configured router port', command: 'proteum dev' },
+            {
+                description: 'Start a worktree or sibling checkout without changing your shell directory',
+                command: 'proteum dev --cwd /path/to/platform-worktree --port 3101 --replace-existing',
+            },
             { description: 'Replace the tracked dev session on another port', command: 'proteum dev --port 3101 --replace-existing' },
             {
                 description: 'Start a tracked dev session with an explicit session file for an agent task',
@@ -134,6 +188,7 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
             },
         ],
         notes: [
+            'Use `--cwd` when the target Proteum app lives in another worktree or checkout and you do not want to `cd` first.',
             'Proteum writes a machine-readable dev session file under `var/run/proteum/dev/<port>.json` by default; override it with `--session-file` when an agent needs a stable path.',
             'Use `--replace-existing` when retries should stop the previously tracked matching session before starting a new one.',
             '`proteum dev list` inspects tracked sessions for the current app root. Add `--stale` to show only orphaned or dead sessions.',
@@ -283,6 +338,25 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         ],
         status: 'stable',
     },
+    orient: {
+        name: 'orient',
+        category: 'Manifest and contracts',
+        summary: 'Resolve owners, guidance files, connected boundaries, and next steps before opening code.',
+        usage: 'proteum orient <query> [--port <port>|--url <baseUrl>] [--json]',
+        bestFor:
+            'Starting multi-repo, generated-artifact, or connected-project work with one explicit orientation step instead of guessing the first files to read.',
+        examples: [
+            { description: 'Orient around a generated controller path', command: 'proteum orient /api/Auth/CurrentUser' },
+            { description: 'Orient around a connected namespace or route', command: 'proteum orient Product.Stats.general' },
+            { description: 'Use a running dev server when the local manifest is unavailable', command: 'proteum orient /domains --port 3101 --json' },
+        ],
+        notes: [
+            'This command combines manifest owner lookup, local or fallback guidance resolution, connected-boundary hints, and three recommended next commands.',
+            'Use it before reading source when the query might map to generated code, connected imports, or framework-owned files.',
+            'When `--port` or `--url` is provided, Proteum can read the manifest from a running dev server instead of only from disk.',
+        ],
+        status: 'experimental',
+    },
     diagnose: {
         name: 'diagnose',
         category: 'Manifest and contracts',
@@ -407,21 +481,37 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
     verify: {
         name: 'verify',
         category: 'Manifest and contracts',
-        summary: 'Validate framework changes against CrossPath, Unique Domains Product, and Unique Domains Website.',
-        usage: 'proteum verify [framework-change] [--crosspath <path>] [--product <path>] [--website <path>] [--crosspath-port <port>] [--product-port <port>] [--website-port <port>] [--route <path>] [--json]',
+        summary: 'Run focused owner/request/browser verification or the full framework reference-app validation pass.',
+        usage: 'proteum verify [framework-change|owner <query>|request <path>|browser <path>] [--port <port>|--url <baseUrl>] [--session-email <email>] [--session-role <role>] [--method <verb>] [--data-json <json>] [--strict-global] [--crosspath <path>] [--product <path>] [--website <path>] [--crosspath-port <port>] [--product-port <port>] [--website-port <port>] [--route <path>] [--json]',
         bestFor:
-            'Framework-repo smoke validation when Proteum changes must be exercised against CrossPath and the website -> product connected-project flow before review.',
+            'Choosing the smallest trustworthy verification surface first, then separating introduced blocking findings from unrelated pre-existing diagnostics.',
         examples: [
             {
                 description: 'Run the default framework smoke verification against the reference apps',
                 command: 'proteum verify framework-change',
             },
+            {
+                description: 'Verify only the owner-scoped chain for a generated controller or route',
+                command: 'proteum verify owner /api/Auth/CurrentUser',
+            },
+            {
+                description: 'Hit one real request against a running dev server and classify findings',
+                command: 'proteum verify request /domains --port 3101',
+            },
+            {
+                description: 'Run browser verification only when the issue is browser-visible',
+                command: 'proteum verify browser /dashboard --port 3101 --session-email admin@example.com --session-role ADMIN',
+            },
             {
                 description: 'Load a specific route in the website validation pass',
                 command: 'proteum verify framework-change --route /domains',
             },
         ],
         notes: [
+            '`proteum verify owner` starts from `proteum orient`, then chooses the smallest trustworthy verify path instead of defaulting to broad global checks.',
+            '`proteum verify owner`, `request`, and `browser` emit `introducedFindings`, `preExistingFindings`, `verificationSteps`, and `result` in JSON.',
+            'Focused verification fails on introduced blocking findings by default and only fails on unrelated pre-existing blockers when `--strict-global` is passed.',
+            '`proteum verify browser` uses an app-local browser workspace under `var/proteum/browser/<run-id>` and never reuses a previous run profile.',
             'When a reference app is already running on the requested port, Proteum reuses it instead of spawning a new `proteum dev` process.',
             'When Proteum spawns the website reference app, it sets the env values consumed by the website `proteum.config.ts` for the product internal and public URLs.',
             'This command is intended for the framework repo and will be most useful where the reference app paths exist locally.',

package/cli/presentation/devSession.ts

@@ -1,8 +1,6 @@
-const React = require('react') as typeof import('react');
-
 import type { TServerReadyConnectedProject } from '../../common/dev/serverHotReload';
 import { renderRows } from './layout';
-import { renderInk } from './ink';
+import { CliReact, renderInk } from './ink';
 import { renderWelcomePanel } from './welcome';
 
 const formatConnectedProjectLabel = (connectedProject: TServerReadyConnectedProject) =>
@@ -66,7 +64,7 @@ export const renderServerReadyBanner = async ({
     connectedProjects?: TServerReadyConnectedProject[];
 }) =>
     renderInk(({ Box, Text }) => {
-        const createElement = React.createElement;
+        const createElement = CliReact.createElement;
         const verifiedConnectedProjects = connectedProjects || [];
 
         return createElement(
@@ -87,7 +85,7 @@ export const renderServerReadyBanner = async ({
                 createElement(
                     Text,
                     { key: `connected-ping-${connectedProject.namespace}`, dimColor: true },
-                    `Ping OK: ${formatConnectedProjectLabel(connectedProject)} responded to /api/__proteum/connected/ping`,
+                    `Ping OK (/ping): ${formatConnectedProjectLabel(connectedProject)}`,
                 ),
             ),
             createElement(Text, { dimColor: true }, `Diagnose /: proteum diagnose / --port ${routerPort}`),
@@ -98,7 +96,7 @@ export const renderServerReadyBanner = async ({
 
 export const renderDevShutdownBanner = async () =>
     renderInk(({ Box, Text }) => {
-        const createElement = React.createElement;
+        const createElement = CliReact.createElement;
 
         return createElement(
             Box,

package/cli/presentation/help.ts

@@ -100,7 +100,7 @@ export const renderCliOverview = async ({
                         const status = command.status === 'experimental' ? ' Experimental.' : '';
 
                         return {
-                            label: command.name === 'init' ? command.usage : `proteum ${command.name}`,
+                            label: command.name === 'init' || command.name === 'configure' ? command.usage : `proteum ${command.name}`,
                             value: `${command.summary}${status}${initNote}`,
                         };
                     }),
@@ -135,7 +135,7 @@ export const renderCliOverview = async ({
                     indent: '  ',
                     nextIndent: '  ',
                 }),
-                wrapText('Every Proteum CLI invocation prints the welcome banner. `proteum dev` is the only command that clears the interactive terminal before rendering its session UI.', {
+                wrapText('Only the bare `proteum build` and bare `proteum dev` commands print the welcome banner and active Proteum installation method. Any extra argument or option skips the banner. `proteum dev` is the only command that clears the interactive terminal before rendering its session UI.', {
                     indent: '  ',
                     nextIndent: '  ',
                 }),

package/cli/presentation/ink.ts

@@ -1,4 +1,4 @@
-const React = require('react') as typeof import('react');
+import { createRequire } from 'module';
 
 import { importEsm } from '../runtime/importEsm';
 import { getTerminalWidth } from './layout';
@@ -13,6 +13,9 @@ type TInkRuntime = {
     StatusMessage: TInkUiModule['StatusMessage'];
 };
 
+// Keep the CLI renderer on the exact React instance Ink resolved for this install shape.
+const CliReact = createRequire(require.resolve('ink'))('react') as typeof import('react');
+
 let inkRuntimePromise: Promise<TInkRuntime> | undefined;
 
 const loadInkRuntime = () => {
@@ -41,7 +44,7 @@ export const renderInk = async (
 
 export const renderTitle = async (title: string, subtitle?: string) =>
     renderInk(({ Box, Text }) => {
-        const createElement = React.createElement;
+        const createElement = CliReact.createElement;
 
         return createElement(
             Box,
@@ -52,18 +55,20 @@ export const renderTitle = async (title: string, subtitle?: string) =>
     });
 
 export const renderSection = async (title: string, body: string) => {
-    const heading = await renderInk(({ Text }) => React.createElement(Text, { bold: true }, title));
+    const heading = await renderInk(({ Text }) => CliReact.createElement(Text, { bold: true }, title));
     return `${heading}\n${body}`;
 };
 
 export const renderStep = async (label: string, message: string) =>
-    renderInk(({ Text }) => React.createElement(Text, { color: 'cyan' }, `${label} ${message}`));
+    renderInk(({ Text }) => CliReact.createElement(Text, { color: 'cyan' }, `${label} ${message}`));
 
 const renderStatusMessage = async (variant: 'success' | 'warning' | 'error', message: string) =>
-    renderInk(({ StatusMessage }) => React.createElement(StatusMessage, { variant }, message));
+    renderInk(({ StatusMessage }) => CliReact.createElement(StatusMessage, { variant }, message));
 
 export const renderSuccess = (message: string) => renderStatusMessage('success', message);
 
 export const renderWarning = (message: string) => renderStatusMessage('warning', message);
 
 export const renderDanger = (message: string) => renderStatusMessage('error', message);
+
+export { CliReact };

package/cli/presentation/welcome.ts

@@ -1,7 +1,5 @@
-const React = require('react') as typeof import('react');
-
 import { renderRows } from './layout';
-import { renderInk } from './ink';
+import { CliReact, renderInk } from './ink';
 
 const ProteumWordmark = [
     String.raw` ____  ____   ___ _____ _____ _   _ __  __`,
@@ -27,7 +25,7 @@ export const renderWelcomePanel = async ({
     tagline: string;
 }) =>
     renderInk(({ Box, Text }) => {
-        const createElement = React.createElement;
+        const createElement = CliReact.createElement;
         const wordmark = ProteumWordmark.map((line) =>
             createElement(Text, { key: line, bold: true, color: 'blue' }, line),
         );

package/cli/runtime/commands.ts

@@ -74,11 +74,53 @@ class CreateCommand extends ProteumCommand {
     }
 }
 
+class ConfigureCommand extends ProteumCommand {
+    public static paths = [['configure']];
+
+    public static usage = buildUsage('configure');
+
+    public args = Option.Rest();
+
+    public async execute() {
+        const [action = '', ...restArgs] = this.args;
+
+        assertNoLegacyArgs('configure', restArgs);
+        this.setCliArgs({
+            action,
+        });
+        await runCommandModule(() => import('../commands/configure'));
+    }
+}
+
+class MigrateCommand extends ProteumCommand {
+    public static paths = [['migrate']];
+
+    public static usage = buildUsage('migrate');
+
+    public cwd = Option.String('--cwd', { description: 'Run the migration against another Proteum app root.' });
+    public dryRun = Option.Boolean('--dry-run', false, { description: 'Print the rewrite plan without writing files.' });
+    public json = Option.Boolean('--json', false, { description: 'Print machine-readable migration output.' });
+    public args = Option.Rest();
+
+    public async execute() {
+        const [action = ''] = this.args;
+
+        this.setCliArgs({
+            action,
+            workdir: this.cwd ?? '',
+            dryRun: this.dryRun,
+            json: this.json,
+        });
+        await runCommandModule(() => import('../commands/migrate'));
+    }
+}
+
 class DevCommand extends ProteumCommand {
     public static paths = [['dev']];
 
     public static usage = buildUsage('dev');
 
+    public cwd = Option.String('--cwd', { description: 'Run the dev command against another Proteum app root.' });
     public json = Option.Boolean('--json', false, { description: 'Print machine-readable dev session output.' });
     public port = Option.String('--port', { description: 'Override the router port.' });
     public cache = Option.Boolean('--cache', true, { description: 'Enable filesystem caching.' });
@@ -105,6 +147,7 @@ class DevCommand extends ProteumCommand {
             action: action || 'start',
             port: this.port ?? '',
             cache: this.cache,
+            workdir: this.cwd ?? '',
             json: this.json,
             sessionFile: this.sessionFile ?? '',
             replaceExisting: this.replaceExisting,
@@ -316,6 +359,30 @@ class ExplainCommand extends ProteumCommand {
     }
 }
 
+class OrientCommand extends ProteumCommand {
+    public static paths = [['orient']];
+
+    public static usage = buildUsage('orient');
+
+    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 json = Option.Boolean('--json', false, { description: 'Print JSON output.' });
+    public args = Option.Rest();
+
+    public async execute() {
+        const query = this.args.join(' ').trim();
+
+        this.setCliArgs({
+            json: this.json,
+            port: this.port ?? '',
+            query,
+            url: this.url ?? '',
+        });
+
+        await runCommandModule(() => import('../commands/orient'));
+    }
+}
+
 class TraceCommand extends ProteumCommand {
     public static paths = [['trace']];
 
@@ -478,6 +545,17 @@ class VerifyCommand extends ProteumCommand {
     public static usage = buildUsage('verify');
 
     public json = Option.Boolean('--json', false, { description: 'Print JSON output.' });
+    public port = Option.String('--port', { description: 'Target an existing dev server on the given port for focused verify actions.' });
+    public url = Option.String('--url', { description: 'Target an existing dev server at the given base URL for focused verify actions.' });
+    public sessionEmail = Option.String('--session-email', {
+        description: 'Mint a dev session before request or browser verification and attach the returned cookie.',
+    });
+    public sessionRole = Option.String('--session-role', { description: 'Require the dev session user to have this role.' });
+    public method = Option.String('--method', { description: 'HTTP method used by request verification.' });
+    public dataJson = Option.String('--data-json', { description: 'JSON request body used by request verification.' });
+    public strictGlobal = Option.Boolean('--strict-global', false, {
+        description: 'Fail focused verification when unrelated pre-existing blocking findings exist.',
+    });
     public crosspath = Option.String('--crosspath', { description: 'Override the CrossPath reference app path.' });
     public product = Option.String('--product', { description: 'Override the Unique Domains Product reference app path.' });
     public website = Option.String('--website', { description: 'Override the Unique Domains Website reference app path.' });
@@ -492,16 +570,25 @@ class VerifyCommand extends ProteumCommand {
     public args = Option.Rest();
 
     public async execute() {
-        const [action = 'framework-change'] = this.args;
+        const [action = 'framework-change', ...restArgs] = this.args;
+        const target = restArgs.join(' ').trim();
 
         this.setCliArgs({
             action,
             crosspath: this.crosspath ?? '',
             crosspathPort: this.crosspathPort ?? '',
+            dataJson: this.dataJson ?? '',
             json: this.json,
+            method: this.method ?? '',
+            port: this.port ?? '',
             product: this.product ?? '',
             productPort: this.productPort ?? '',
             route: this.route ?? '',
+            sessionEmail: this.sessionEmail ?? '',
+            sessionRole: this.sessionRole ?? '',
+            strictGlobal: this.strictGlobal,
+            target,
+            url: this.url ?? '',
             website: this.website ?? '',
             websitePort: this.websitePort ?? '',
         });
@@ -513,6 +600,8 @@ class VerifyCommand extends ProteumCommand {
 export const registeredCommands = {
     init: InitCommand,
     create: CreateCommand,
+    configure: ConfigureCommand,
+    migrate: MigrateCommand,
     dev: DevCommand,
     refresh: RefreshCommand,
     build: BuildCommand,
@@ -522,6 +611,7 @@ export const registeredCommands = {
     connect: ConnectCommand,
     doctor: DoctorCommand,
     explain: ExplainCommand,
+    orient: OrientCommand,
     diagnose: DiagnoseCommand,
     perf: PerfCommand,
     trace: TraceCommand,
@@ -542,6 +632,8 @@ export const createCli = (version: string) => {
     clipanion.register(Builtins.DefinitionsCommand);
     clipanion.register(InitCommand);
     clipanion.register(CreateCommand);
+    clipanion.register(ConfigureCommand);
+    clipanion.register(MigrateCommand);
     clipanion.register(DevCommand);
     clipanion.register(RefreshCommand);
     clipanion.register(BuildCommand);
@@ -551,6 +643,7 @@ export const createCli = (version: string) => {
     clipanion.register(ConnectCommand);
     clipanion.register(DoctorCommand);
     clipanion.register(ExplainCommand);
+    clipanion.register(OrientCommand);
     clipanion.register(DiagnoseCommand);
     clipanion.register(PerfCommand);
     clipanion.register(TraceCommand);

package/cli/scaffold/index.ts

@@ -5,7 +5,7 @@ import { UsageError } from 'clipanion';
 
 import cli from '..';
 import { loadApplicationIdentityConfig } from '../../common/applicationConfigLoader';
-import { ensureProjectAgentSymlinks, renderProjectInstructionGitignoreBlock } from '../utils/agents';
+import { renderProjectInstructionGitignoreBlock } from '../utils/agents';
 import { runProcess } from '../utils/runProcess';
 import {
     createClientTsconfigTemplate,
@@ -705,7 +705,6 @@ export const runInitScaffold = async () => {
     if (!result.dryRun) {
         fs.ensureDirSync(path.join(appRoot, 'client'));
         fs.ensureDirSync(path.join(appRoot, 'server'));
-        ensureProjectAgentSymlinks({ appRoot, coreRoot: cli.paths.core.root });
     }
 
     if (config.install) {
@@ -728,6 +727,7 @@ export const runInitScaffold = async () => {
               ? 'Run `npm run dev` in the new app directory.'
               : 'Run `npm install`, then `npm run dev` in the new app directory.',
     );
+    result.nextSteps.push('Run `proteum configure agents` when you want Proteum-managed instruction symlinks.');
     result.nextSteps.push('Use `proteum create page|controller|command|route|service ...` to add app artifacts.');
 
     printResult(result, createInitSummary(result, config));

package/cli/scaffold/templates.ts

@@ -26,9 +26,11 @@ export const createPageTemplate = ({
 
 Router.page(
     ${JSON.stringify(routePath)},
+    {
+        auth: false,
+        layout: false,
+    },
     () => ({
-        _auth: false,
-        _layout: false,
         heading: ${JSON.stringify(heading)},
         message: ${JSON.stringify(message)},
     }),