proteum 2.3.0 → 2.4.1

package/cli/presentation/commands.ts

@@ -128,7 +128,7 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         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 instruction files.',
             'Standalone mode writes tracked instruction files into the current Proteum app root.',
-            'Monorepo mode writes reusable root documents such as `AGENTS.md`, `CODING_STYLE.md`, `diagnostics.md`, and `optimizations.md` into the chosen monorepo root, then writes only app-root and area instruction files into the current Proteum app root.',
+            'Monorepo mode writes reusable root documents such as `AGENTS.md`, `DOCUMENTATION.md`, `CODING_STYLE.md`, `diagnostics.md`, and `optimizations.md` into the chosen monorepo root, then writes only app-root and area instruction files into the current Proteum app root.',
             'Every managed instruction file contains a `# Proteum Instructions` section with the full embedded Proteum project instruction corpus.',
             'Existing content outside `# Proteum Instructions` is preserved. Directories and foreign symlinks are replaced only after confirmation.',
         ],
@@ -170,11 +170,14 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
             { 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',
+                command: 'proteum dev --cwd /path/to/platform-worktree --port 3101',
             },
-            { 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',
+                command: 'proteum dev --port 3101 --session-file var/run/proteum/dev/agents/task.json',
+            },
+            {
+                description: 'Restart the exact tracked session file from the current task',
                 command: 'proteum dev --port 3101 --session-file var/run/proteum/dev/agents/task.json --replace-existing',
             },
             {
@@ -193,8 +196,9 @@ 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.',
+            'Before registering a new session, Proteum removes stale same-worktree session files and fails fast if another live tracked session remains.',
             'Before the dev loop starts, Proteum ensures tracked instruction files contain the current managed `# Proteum Instructions` section.',
-            'Use `--replace-existing` when retries should stop the previously tracked matching session before starting a new one.',
+            'Use `--replace-existing` only when retrying the exact requested session file.',
             '`proteum dev list` inspects tracked sessions for the current app root. Add `--stale` to show only orphaned or dead sessions.',
             '`proteum dev stop` targets the current session file by default. Add `--all` to stop every tracked session for the current app root.',
             '`proteum dev` clears the interactive terminal once at startup, then shows `CTRL+R` reload and `CTRL+C` shutdown hotkeys in the session banner.',
@@ -359,11 +363,15 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         examples: [
             { description: 'Show the default compact agent summary', command: 'proteum explain' },
             {
-                description: 'Inspect generated routes, controllers, and commands together',
+                description: 'Summarize generated routes, controllers, and commands together',
                 command: 'proteum explain --routes --controllers --commands',
             },
             {
-                description: 'Inspect configured connected projects and imported controllers',
+                description: 'Emit selected route/controller/command arrays only when needed',
+                command: 'proteum explain --routes --controllers --commands --full',
+            },
+            {
+                description: 'Summarize configured connected projects and imported controllers',
                 command: 'proteum explain --connected --controllers',
             },
             { description: 'Resolve the most likely manifest owner for a path or file', command: 'proteum explain owner /api/Auth/CurrentUser' },
@@ -371,7 +379,7 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         ],
         notes: [
             'Default output is compact `proteum-agent-v1` JSON because the CLI is optimized for agents.',
-            '`--full`, `--manifest`, or explicit section flags are the escape hatch for large details.',
+            'Explicit section flags summarize those sections by default; add `--full` or use `--manifest` for raw manifest arrays.',
             'Legacy positional section selection remains supported, for example `proteum explain routes services`.',
             '`proteum explain owner <query>` ranks matching routes, controllers, services, commands, layouts, and diagnostics from the manifest.',
             'Connected projects are emitted from explicit `proteum.config.ts` `connect.<Namespace>.*` values plus the resolved connected contract.',
@@ -391,7 +399,7 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
             { description: 'Use a running dev server when the local manifest is unavailable', command: 'proteum orient /domains --port 3101' },
         ],
         notes: [
-            'Default output is compact `proteum-agent-v1` JSON with `mustRead`, conditional docs, owner matches, and next commands.',
+            'Default output is compact `proteum-agent-v1` JSON with `mustRead`, triggered instruction files, conditional docs, owner matches, and next commands.',
             'Use it before reading source when the query might map to generated code, connected imports, framework-owned files, or area instructions.',
             'When `--port` or `--url` is provided, Proteum can read the manifest from a running dev server instead of only from disk.',
         ],
@@ -457,6 +465,10 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         ],
         notes: [
             'Default output is compact `proteum-agent-v1` JSON with the selected session, health, and next command.',
+            'When no tracked session exists, the configured router and HMR ports are inspected before suggesting Start Dev.',
+            'If the same app already responds on the configured port, the next action uses or repairs that runtime instead of starting a second server.',
+            'The selected live session includes its dev-hosted MCP URL when available.',
+            'Use this command instead of curling page routes to identify port ownership.',
             'Use `--full` to include every tracked session field.',
         ],
         status: 'experimental',
@@ -464,26 +476,24 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
     mcp: {
         name: 'mcp',
         category: 'Manifest and contracts',
-        summary: 'Start a read-only Proteum MCP server for compact agent diagnostics and runtime data.',
-        usage: 'proteum mcp [--cwd <path>] [--url <baseUrl>] [--session-file <path>]',
+        summary: 'Start or attach to the machine-scope MCP router for live Proteum dev projects.',
+        usage: 'proteum mcp [status|stop] [--stdio|--daemon] [--port <port>]',
         bestFor:
-            'Agent integrations that need repeated low-token access to Proteum manifest, instruction routing, runtime status, trace, perf, diagnose, and log summaries.',
+            'Registering a single MCP server in an LLM and keeping one managed machine daemon available while dev servers run.',
         examples: [
-            { description: 'Start the MCP server for the current app over stdio', command: 'proteum mcp' },
-            {
-                description: 'Point the MCP server at a running dev server',
-                command: 'proteum mcp --url http://localhost:3101',
-            },
-            {
-                description: 'Resolve runtime data from an explicit tracked session file',
-                command: 'proteum mcp --session-file var/run/proteum/dev/agents/task.json',
-            },
+            { description: 'Start or reuse the managed machine MCP daemon from a terminal', command: 'proteum mcp' },
+            { description: 'Force stdio MCP transport for an MCP client', command: 'proteum mcp --stdio' },
+            { description: 'Inspect the managed machine MCP daemon', command: 'proteum mcp status' },
         ],
         notes: [
-            '`proteum mcp` is read-only in v1 and does not start/stop dev servers, refresh generated code, write files, or mutate traces.',
-            'Tool and resource payloads are compact single-line `proteum-mcp-v1` JSON for low-token agent reads.',
-            'Use the CLI for reproducible build/dev/check workflows; use MCP for repeated agent reads and progressive detail loading.',
-            'A running `proteum dev` server also exposes the same tool contract at `/__proteum/mcp` for runtime-adjacent access.',
+            '`proteum dev` ensures one managed machine MCP daemon is running before the app dev loop starts.',
+            '`proteum mcp` is a router, not an app dev server. It discovers live `proteum dev` sessions from the machine registry and can resolve offline app candidates from `cwd`.',
+            'Agents should call MCP `workflow_start` with `cwd` or a known `projectId`; use `project_resolve { cwd }` when routing is ambiguous or no live dev server exists yet.',
+            'When an offline app candidate is returned, start exactly one `proteum dev` from that app root before runtime diagnose, trace, or perf reads.',
+            'After an MCP read succeeds, agents should not run the equivalent CLI command or broad owner search for the same runtime state.',
+            'App runtime data still comes from the selected dev-hosted `/__proteum/mcp` endpoint.',
+            'Only one managed machine MCP daemon may run at a time; stale daemon records are cleaned automatically.',
+            'MCP remains read-only and optimized for compact `proteum-mcp-v1` payloads.',
         ],
         status: 'experimental',
     },

package/cli/presentation/help.ts

@@ -174,7 +174,7 @@ export const renderCommandHelp = async ({
     const notes = [...(command.notes ?? [])];
 
     if (commandName === 'init') notes.push(getInitAvailabilityNote(initAvailable));
-    if (commandName !== 'init' && !isLikelyProteumAppRoot(workdir)) {
+    if (commandName !== 'init' && commandName !== 'mcp' && !isLikelyProteumAppRoot(workdir)) {
         notes.push(
             'This command expects to run inside a Proteum app root. The current directory does not contain the usual `client/` and `server/` folders.',
         );

package/cli/runtime/commands.ts

@@ -1,8 +1,72 @@
 import { Builtins, Cli, Option } from 'clipanion';
+import path from 'path';
 
-import type { TArgsObject } from '../context';
+import cli, { type TArgsObject } from '../context';
 import { applyLegacyBooleanArgs, assertNoLegacyArgs } from './argv';
 import { buildUsage, ProteumCommand, runCommandModule } from './command';
+import { createStartDevCommand, quoteShellPath, resolveProteumAppRootContext } from '../utils/appRoots';
+import { printJson } from '../utils/agentOutput';
+
+const createRunInAppCommand = ({
+    appRoot,
+    baseRoot,
+    command,
+}: {
+    appRoot: string;
+    baseRoot: string;
+    command: string;
+}) => {
+    const relativeAppRoot = path.relative(baseRoot, appRoot) || '.';
+    if (relativeAppRoot === '.') return command;
+    return `cd ${quoteShellPath(relativeAppRoot)} && ${command}`;
+};
+
+const printNonAppRootResponse = ({
+    commandName,
+    cwd,
+}: {
+    commandName: 'dev' | 'runtime';
+    cwd: string;
+}) => {
+    const context = resolveProteumAppRootContext(cwd);
+    const appCandidates = context.appCandidates;
+    const commandLabel = commandName === 'dev' ? 'Dev' : 'Runtime Status';
+
+    printJson({
+        ok: false,
+        format: 'proteum-agent-v1',
+        summary:
+            appCandidates.length > 0
+                ? `${cwd} is a Proteum workspace wrapper or nested directory, not an app root. Found ${appCandidates.length} app candidate${appCandidates.length === 1 ? '' : 's'}.`
+                : `${cwd} is not a Proteum app root.`,
+        data: {
+            cwd: context.cwd,
+            appCandidates,
+        },
+        nextActions: appCandidates.map((candidate) => ({
+            label: `${commandLabel}: ${candidate.relativeAppRoot || candidate.appRoot}`,
+            command:
+                commandName === 'dev'
+                    ? createStartDevCommand({
+                          appRoot: candidate.appRoot,
+                          baseRoot: context.cwd,
+                          port: candidate.manifest?.routerPort,
+                      })
+                    : createRunInAppCommand({
+                          appRoot: candidate.appRoot,
+                          baseRoot: context.cwd,
+                          command: 'npx proteum runtime status',
+                      }),
+            reason:
+                commandName === 'dev'
+                    ? 'Start Proteum dev from the app root, not the workspace wrapper.'
+                    : 'Inspect tracked runtime sessions from the app root, not the workspace wrapper.',
+        })),
+    });
+    process.exitCode = 1;
+};
+
+const isCurrentWorkdirProteumAppRoot = () => resolveProteumAppRootContext(String(cli.args.workdir || process.cwd())).isAppRoot;
 
 class InitCommand extends ProteumCommand {
     public static paths = [['init']];
@@ -154,6 +218,10 @@ class DevCommand extends ProteumCommand {
             all: this.all,
             stale: this.stale,
         });
+        if (!isCurrentWorkdirProteumAppRoot()) {
+            printNonAppRootResponse({ commandName: 'dev', cwd: String(cli.args.workdir || process.cwd()) });
+            return 1;
+        }
         await runCommandModule(() => import('../commands/dev'));
     }
 }
@@ -371,18 +439,18 @@ class ExplainCommand extends ProteumCommand {
     public full = Option.Boolean('--full', false, { description: 'Print the full selected machine-readable detail.' });
     public human = Option.Boolean('--human', false, { description: 'Print the legacy human-readable report.' });
     public manifest = Option.Boolean('--manifest', false, { description: 'Print the full generated manifest.' });
-    public all = Option.Boolean('--all', false, { description: 'Include every explain section.' });
-    public app = Option.Boolean('--app', false, { description: 'Include the app section.' });
-    public conventions = Option.Boolean('--conventions', false, { description: 'Include the conventions section.' });
-    public env = Option.Boolean('--env', false, { description: 'Include the env section.' });
-    public connected = Option.Boolean('--connected', false, { description: 'Include the connected-projects section.' });
-    public services = Option.Boolean('--services', false, { description: 'Include the services section.' });
-    public controllers = Option.Boolean('--controllers', false, { description: 'Include the controllers section.' });
-    public commands = Option.Boolean('--commands', false, { description: 'Include the commands section.' });
-    public routes = Option.Boolean('--routes', false, { description: 'Include the routes section.' });
-    public layouts = Option.Boolean('--layouts', false, { description: 'Include the layouts section.' });
+    public all = Option.Boolean('--all', false, { description: 'Summarize every explain section; add --full for raw arrays.' });
+    public app = Option.Boolean('--app', false, { description: 'Summarize the app section; add --full for raw detail.' });
+    public conventions = Option.Boolean('--conventions', false, { description: 'Summarize the conventions section; add --full for raw detail.' });
+    public env = Option.Boolean('--env', false, { description: 'Summarize the env section; add --full for raw detail.' });
+    public connected = Option.Boolean('--connected', false, { description: 'Summarize the connected-projects section; add --full for raw detail.' });
+    public services = Option.Boolean('--services', false, { description: 'Summarize the services section; add --full for raw detail.' });
+    public controllers = Option.Boolean('--controllers', false, { description: 'Summarize the controllers section; add --full for raw detail.' });
+    public commands = Option.Boolean('--commands', false, { description: 'Summarize the commands section; add --full for raw detail.' });
+    public routes = Option.Boolean('--routes', false, { description: 'Summarize the routes section; add --full for raw detail.' });
+    public layouts = Option.Boolean('--layouts', false, { description: 'Summarize the layouts section; add --full for raw detail.' });
     public diagnostics = Option.Boolean('--diagnostics', false, {
-        description: 'Include the diagnostics section.',
+        description: 'Summarize the diagnostics section; add --full for raw detail.',
     });
     public args = Option.Rest();
 
@@ -633,6 +701,9 @@ class RuntimeCommand extends ProteumCommand {
     public static usage = buildUsage('runtime');
 
     public full = Option.Boolean('--full', false, { description: 'Print full tracked-session and health detail.' });
+    public manifest = Option.Boolean('--manifest', false, {
+        description: 'Unsupported compatibility guard. Use `proteum explain --manifest` instead.',
+    });
     public sessionFile = Option.String('--session-file', {
         description: 'Inspect one explicit dev session file instead of the app registry.',
     });
@@ -644,9 +715,35 @@ class RuntimeCommand extends ProteumCommand {
         this.setCliArgs({
             action,
             full: this.full,
+            manifest: this.manifest,
             sessionFile: this.sessionFile ?? '',
         });
 
+        if (this.manifest) {
+            printJson({
+                ok: false,
+                format: 'proteum-agent-v1',
+                summary: '`proteum runtime status --manifest` is not supported. Use `proteum explain --manifest` from the app root.',
+                data: {
+                    command: 'proteum runtime status --manifest',
+                },
+                nextActions: [
+                    {
+                        label: 'Explain Manifest',
+                        command: 'npx proteum explain --manifest',
+                        reason: 'The generated manifest belongs to the explain command, not runtime status.',
+                    },
+                ],
+            });
+            process.exitCode = 1;
+            return 1;
+        }
+
+        if (!isCurrentWorkdirProteumAppRoot()) {
+            printNonAppRootResponse({ commandName: 'runtime', cwd: String(cli.args.workdir || process.cwd()) });
+            return 1;
+        }
+
         await runCommandModule(() => import('../commands/runtime'));
     }
 }
@@ -656,19 +753,30 @@ class McpCommand extends ProteumCommand {
 
     public static usage = buildUsage('mcp');
 
-    public cwd = Option.String('--cwd', { description: 'Run the MCP server against another Proteum app root.' });
-    public sessionFile = Option.String('--session-file', {
-        description: 'Inspect one explicit dev session file when resolving runtime data.',
+    public daemon = Option.Boolean('--daemon', false, {
+        description: 'Run the managed machine-scope MCP daemon over local HTTP.',
     });
-    public url = Option.String('--url', { description: 'Use a running Proteum dev server as the live runtime data source.' });
-    public legacyArgs = Option.Rest();
+    public stdio = Option.Boolean('--stdio', false, {
+        description: 'Force stdio MCP transport for an MCP client.',
+    });
+    public port = Option.String('--port', {
+        description: 'Port for the managed machine MCP daemon.',
+    });
+    public json = Option.Boolean('--json', false, {
+        description: 'Print machine-readable daemon status output.',
+    });
+    public args = Option.Rest();
 
     public async execute() {
-        assertNoLegacyArgs('mcp', this.legacyArgs);
+        const [action = 'start', ...restArgs] = this.args;
+
+        assertNoLegacyArgs('mcp', restArgs);
         this.setCliArgs({
-            sessionFile: this.sessionFile ?? '',
-            url: this.url ?? '',
-            workdir: this.cwd ?? '',
+            action,
+            daemon: this.daemon,
+            stdio: this.stdio,
+            port: this.port ?? '',
+            json: this.json,
         });
 
         await runCommandModule(() => import('../commands/mcp'));