proteum 2.2.8 → 2.3.0

package/cli/presentation/commands.ts

@@ -21,6 +21,8 @@ export const proteumCommandNames = [
     'orient',
     'diagnose',
     'perf',
+    'runtime',
+    'mcp',
     'trace',
     'command',
     'session',
@@ -49,7 +51,7 @@ export type TProteumCommandDoc = {
 
 export const proteumRecommendedFlow: TRow[] = [
     { 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: '2. proteum runtime status', value: 'Reuse an existing tracked dev session before starting a new one.' },
     { 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.' },
 ];
@@ -57,7 +59,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', 'e2e'] },
-    { title: 'Manifest and contracts', names: ['connect', 'doctor', 'explain', 'orient', 'diagnose', 'perf', 'trace', 'command', 'session', 'verify'] },
+    { title: 'Manifest and contracts', names: ['connect', 'doctor', 'explain', 'orient', 'diagnose', 'perf', 'runtime', 'mcp', 'trace', 'command', 'session', 'verify'] },
     { title: 'Project scaffolding', names: ['init', 'configure', 'create', 'migrate'] },
 ];
 
@@ -124,9 +126,9 @@ 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 `AGENTS.md` file.',
+            '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 the reusable root `AGENTS.md` into the chosen monorepo root and the app-root 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.',
             '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.',
         ],
@@ -310,16 +312,17 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         name: 'connect',
         category: 'Manifest and contracts',
         summary: 'Inspect connected-project config, cached contracts, and imported controllers.',
-        usage: 'proteum connect [--controllers] [--json] [--strict]',
+        usage: 'proteum connect [--controllers] [--full|--human] [--strict]',
         bestFor:
             'Auditing the current app connect setup without manually stitching together refresh, explain, env inspection, and contract checks.',
         examples: [
-            { description: 'Print a human-readable connected-project summary', command: 'proteum connect' },
+            { description: 'Print a compact connected-project summary', command: 'proteum connect' },
             { description: 'Include imported connected controllers', command: 'proteum connect --controllers' },
-            { description: 'Emit machine-readable connect output', command: 'proteum connect --json' },
+            { description: 'Emit the full connect payload', command: 'proteum connect --full' },
             { description: 'Fail when connect diagnostics exist', command: 'proteum connect --strict' },
         ],
         notes: [
+            'Default output is compact `proteum-agent-v1` JSON.',
             'Proteum refreshes generated typings before reading the connect manifest state.',
             'This command inspects explicit `proteum.config.ts` connected sources and URLs, cached `.proteum/connected/*.json` files, and imported connected controllers.',
             '`--strict` is intended for CI or framework validation when connected contracts must be present and usable.',
@@ -330,27 +333,31 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         name: 'doctor',
         category: 'Manifest and contracts',
         summary: 'Inspect the generated Proteum manifest diagnostics.',
-        usage: 'proteum doctor [--contracts] [--json] [--strict]',
+        usage: 'proteum doctor [--contracts] [--full|--human] [--strict]',
         bestFor:
             'Auditing manifest warnings and errors, especially in CI or when route/controller generation behaves unexpectedly.',
         examples: [
-            { description: 'Print a human-readable diagnostic summary', command: 'proteum doctor' },
+            { description: 'Print a compact diagnostic summary', command: 'proteum doctor' },
             { description: 'Inspect missing generated contracts and source files', command: 'proteum doctor --contracts' },
             { description: 'Fail if any diagnostics exist', command: 'proteum doctor --strict' },
-            { description: 'Emit machine-readable diagnostics', command: 'proteum doctor --json' },
+            { description: 'Emit the full diagnostic payload', command: 'proteum doctor --full' },
+        ],
+        notes: [
+            'Default output is compact `proteum-agent-v1` JSON.',
+            '`--strict` is intended for CI and pre-release verification.',
+            '`--contracts` checks manifest-owned source files and expected generated artifacts on disk.',
         ],
-        notes: ['`--strict` is intended for CI and pre-release verification.', '`--contracts` checks manifest-owned source files and expected generated artifacts on disk.'],
         status: 'stable',
     },
     explain: {
         name: 'explain',
         category: 'Manifest and contracts',
         summary: 'Explain the generated Proteum manifest.',
-        usage: 'proteum explain [owner <query>] [--all|--app|--conventions|--env|--connected|--services|--controllers|--commands|--routes|--layouts|--diagnostics] [--json]',
+        usage: 'proteum explain [owner <query>] [--manifest|--full|--human|--all|--app|--conventions|--env|--connected|--services|--controllers|--commands|--routes|--layouts|--diagnostics]',
         bestFor:
-            'Inspecting how source files became generated routes, controllers, commands, layouts, services, and diagnostics without reading compiler internals.',
+            'Inspecting the compact generated-app summary first, then opening selected manifest sections only when needed.',
         examples: [
-            { description: 'Show the default human summary', command: 'proteum explain' },
+            { description: 'Show the default compact agent summary', command: 'proteum explain' },
             {
                 description: 'Inspect generated routes, controllers, and commands together',
                 command: 'proteum explain --routes --controllers --commands',
@@ -360,9 +367,11 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
                 command: 'proteum explain --connected --controllers',
             },
             { description: 'Resolve the most likely manifest owner for a path or file', command: 'proteum explain owner /api/Auth/CurrentUser' },
-            { description: 'Emit the selected manifest sections as JSON', command: 'proteum explain --routes --json' },
+            { description: 'Emit the full manifest only when needed', command: 'proteum explain --manifest' },
         ],
         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.',
             '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.',
@@ -373,17 +382,17 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         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]',
+        usage: 'proteum orient <query> [--port <port>|--url <baseUrl>] [--full|--human]',
         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' },
+            { description: 'Use a running dev server when the local manifest is unavailable', command: 'proteum orient /domains --port 3101' },
         ],
         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.',
+            'Default output is compact `proteum-agent-v1` JSON with `mustRead`, 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.',
         ],
         status: 'experimental',
@@ -392,7 +401,7 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         name: 'diagnose',
         category: 'Manifest and contracts',
         summary: 'Combine owner lookup, doctor output, contract checks, traces, and server logs into one report.',
-        usage: 'proteum diagnose [<query>] [--hit <path>] [--method <verb>] [--data-json <json>] [--session-email <email>] [--session-role <role>] [--port <port>|--url <baseUrl>] [--json]',
+        usage: 'proteum diagnose [<query>] [--hit <path>] [--method <verb>] [--data-json <json>] [--session-email <email>] [--session-role <role>] [--port <port>|--url <baseUrl>] [--full|--human]',
         bestFor:
             'Collapsing the usual explain + doctor + trace + session + server log loop into one structured debugging pass.',
         examples: [
@@ -401,6 +410,8 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
             { description: 'Diagnose an API call with a JSON payload', command: 'proteum diagnose /api/Auth/CurrentUser --hit /api/Auth/CurrentUser --method POST --data-json "{}"' },
         ],
         notes: [
+            'Default output is compact `proteum-agent-v1` JSON and omits raw request events, payloads, and SQL text.',
+            'Use `--full` only when the compact response says lower-level detail is required.',
             'This command talks to the running app over the dev-only diagnostics, trace, and session endpoints.',
             'When `--hit` is omitted, Proteum diagnoses the latest matching request trace if one already exists.',
         ],
@@ -410,7 +421,7 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         name: 'perf',
         category: 'Manifest and contracts',
         summary: 'Inspect shared performance rollups built from live request traces on a running Proteum dev server.',
-        usage: 'proteum perf [top|request <requestId|path>|compare|memory] [--since <window>] [--baseline <window>] [--target <window>] [--group-by <path|route|controller>] [--limit <n>] [--port <port>|--url <baseUrl>] [--json]',
+        usage: 'proteum perf [top|request <requestId|path>|compare|memory] [--since <window>] [--baseline <window>] [--target <window>] [--group-by <path|route|controller>] [--limit <n>] [--port <port>|--url <baseUrl>] [--full|--human]',
         bestFor:
             'Finding the routes or controllers with the biggest response-time, CPU, SQL, render, and memory impact without manually stitching traces together.',
         examples: [
@@ -426,17 +437,61 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
             },
         ],
         notes: [
+            'Default output is compact `proteum-agent-v1` JSON with capped rows and next commands.',
             'Perf data is derived from the same dev-only request trace buffer used by `proteum trace` and the profiler.',
             'Window values accept `1h`, `6h`, `24h`, `today`, `yesterday`, or an ISO timestamp.',
             'Older traces captured before the perf runtime metrics were added may not include CPU or memory deltas.',
         ],
         status: 'experimental',
     },
+    runtime: {
+        name: 'runtime',
+        category: 'Manifest and contracts',
+        summary: 'Inspect the current app manifest, tracked dev sessions, and runtime health in one compact response.',
+        usage: 'proteum runtime status [--session-file <path>] [--full]',
+        bestFor:
+            'Reusing a live dev session and avoiding repeated dev-list, manifest, and health-check commands before request diagnostics.',
+        examples: [
+            { description: 'Resolve the current runtime status', command: 'proteum runtime status' },
+            { description: 'Inspect one explicit session file', command: 'proteum runtime status --session-file var/run/proteum/dev/agents/task.json' },
+        ],
+        notes: [
+            'Default output is compact `proteum-agent-v1` JSON with the selected session, health, and next command.',
+            'Use `--full` to include every tracked session field.',
+        ],
+        status: 'experimental',
+    },
+    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>]',
+        bestFor:
+            'Agent integrations that need repeated low-token access to Proteum manifest, instruction routing, runtime status, trace, perf, diagnose, and log summaries.',
+        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',
+            },
+        ],
+        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.',
+        ],
+        status: 'experimental',
+    },
     trace: {
         name: 'trace',
         category: 'Manifest and contracts',
         summary: 'Inspect live in-memory request traces from a running Proteum dev server.',
-        usage: 'proteum trace [latest|show <requestId>|requests|arm|export <requestId>] [--port <port>|--url <baseUrl>] [--json]',
+        usage: 'proteum trace [latest|show <requestId>|requests|arm|export <requestId>] [--port <port>|--url <baseUrl>] [--events|--full|--human]',
         bestFor:
             'Debugging route resolution, context creation, SSR payloads, renders, and runtime errors without attaching a debugger.',
         examples: [
@@ -447,6 +502,8 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
             { description: 'Target a custom dev base URL directly', command: 'proteum trace latest --url http://127.0.0.1:3010' },
         ],
         notes: [
+            'Default output is compact `proteum-agent-v1` JSON with counts, errors, hot calls, and hot SQL only.',
+            'Use `--events` or `--full` to print the raw event stream, payload summaries, and SQL text.',
             'This command talks to the running app over the dev-only `__proteum/trace` HTTP endpoints.',
             'Traces are stored in a bounded in-memory buffer with payload summarization and sensitive-field redaction.',
             'Use `--port` when the app is not running on the router port declared in `PORT`, or `--url` when the host itself is non-standard.',

package/cli/presentation/devSession.ts

@@ -35,6 +35,7 @@ export const renderDevSession = async ({
                 { label: 'root', value: appRoot },
                 { label: 'router', value: `http://localhost:${routerPort}` },
                 { label: 'hmr', value: `http://localhost:${devEventPort}/__proteum_hmr` },
+                { label: 'mcp', value: `http://localhost:${routerPort}/__proteum/mcp` },
                 ...(connectedProjects && connectedProjects.length > 0
                     ? connectedProjects.map((connectedProject) => ({
                           label: `connect ${connectedProject.namespace}`,
@@ -91,6 +92,7 @@ export const renderServerReadyBanner = async ({
             createElement(Text, { dimColor: true }, `Diagnose /: proteum diagnose / --port ${routerPort}`),
             createElement(Text, { dimColor: true }, `Perf top: proteum perf top --port ${routerPort}`),
             createElement(Text, { dimColor: true }, `Trace latest: proteum trace latest --port ${routerPort}`),
+            createElement(Text, { dimColor: true }, `MCP: ${publicUrl}/__proteum/mcp`),
         );
     });
 

package/cli/runtime/commands.ts

@@ -324,14 +324,16 @@ class ConnectCommand extends ProteumCommand {
     public controllers = Option.Boolean('--controllers', false, {
         description: 'Include imported connected controllers in the output.',
     });
-    public json = Option.Boolean('--json', false, { description: 'Print JSON output.' });
+    public json = Option.Boolean('--json', false, { description: 'Compatibility flag; compact JSON is the default output.' });
+    public full = Option.Boolean('--full', false, { description: 'Print the full connect payload.' });
+    public human = Option.Boolean('--human', false, { description: 'Print the legacy human-readable report.' });
     public strict = Option.Boolean('--strict', false, { description: 'Exit with failure if any connect diagnostics exist.' });
     public legacyArgs = Option.Rest();
 
     public async execute() {
-        const args = { controllers: this.controllers, json: this.json, strict: this.strict } satisfies TArgsObject;
+        const args = { controllers: this.controllers, full: this.full, human: this.human, json: this.json, strict: this.strict } satisfies TArgsObject;
 
-        applyLegacyBooleanArgs('connect', this.legacyArgs, ['controllers', 'json', 'strict'], args);
+        applyLegacyBooleanArgs('connect', this.legacyArgs, ['controllers', 'full', 'human', 'json', 'strict'], args);
         this.setCliArgs(args);
         await runCommandModule(() => import('../commands/connect'));
     }
@@ -345,14 +347,16 @@ class DoctorCommand extends ProteumCommand {
     public contracts = Option.Boolean('--contracts', false, {
         description: 'Run contract-focused diagnostics for generated artifacts and manifest-owned source files.',
     });
-    public json = Option.Boolean('--json', false, { description: 'Print JSON output.' });
+    public json = Option.Boolean('--json', false, { description: 'Compatibility flag; compact JSON is the default output.' });
+    public full = Option.Boolean('--full', false, { description: 'Print the full doctor payload.' });
+    public human = Option.Boolean('--human', false, { description: 'Print the legacy human-readable report.' });
     public strict = Option.Boolean('--strict', false, { description: 'Exit with failure if any diagnostics exist.' });
     public legacyArgs = Option.Rest();
 
     public async execute() {
-        const args = { contracts: this.contracts, json: this.json, strict: this.strict } satisfies TArgsObject;
+        const args = { contracts: this.contracts, full: this.full, human: this.human, json: this.json, strict: this.strict } satisfies TArgsObject;
 
-        applyLegacyBooleanArgs('doctor', this.legacyArgs, ['contracts', 'json', 'strict'], args);
+        applyLegacyBooleanArgs('doctor', this.legacyArgs, ['contracts', 'full', 'human', 'json', 'strict'], args);
         this.setCliArgs(args);
         await runCommandModule(() => import('../commands/doctor'));
     }
@@ -363,7 +367,10 @@ class ExplainCommand extends ProteumCommand {
 
     public static usage = buildUsage('explain');
 
-    public json = Option.Boolean('--json', false, { description: 'Print JSON output.' });
+    public json = Option.Boolean('--json', false, { description: 'Compatibility flag; compact JSON is the default output.' });
+    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.' });
@@ -384,6 +391,9 @@ class ExplainCommand extends ProteumCommand {
         if (mode === 'owner') {
             this.setCliArgs({
                 json: this.json,
+                full: this.full,
+                human: this.human,
+                manifest: this.manifest,
                 ownerQuery: restArgs.join(' ').trim(),
             });
             await runCommandModule(() => import('../commands/explain'));
@@ -392,6 +402,9 @@ class ExplainCommand extends ProteumCommand {
 
         const args = {
             json: this.json,
+            full: this.full,
+            human: this.human,
+            manifest: this.manifest,
             all: this.all,
             app: this.app,
             conventions: this.conventions,
@@ -408,7 +421,7 @@ class ExplainCommand extends ProteumCommand {
         applyLegacyBooleanArgs(
             'explain',
             this.args,
-            ['json', 'all', 'app', 'conventions', 'env', 'connected', 'services', 'controllers', 'commands', 'routes', 'layouts', 'diagnostics'],
+            ['json', 'full', 'human', 'manifest', 'all', 'app', 'conventions', 'env', 'connected', 'services', 'controllers', 'commands', 'routes', 'layouts', 'diagnostics'],
             args,
         );
         this.setCliArgs(args);
@@ -423,7 +436,9 @@ class OrientCommand extends ProteumCommand {
 
     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 json = Option.Boolean('--json', false, { description: 'Compatibility flag; compact JSON is the default output.' });
+    public full = Option.Boolean('--full', false, { description: 'Print the full orientation payload.' });
+    public human = Option.Boolean('--human', false, { description: 'Print the legacy human-readable report.' });
     public args = Option.Rest();
 
     public async execute() {
@@ -431,6 +446,8 @@ class OrientCommand extends ProteumCommand {
 
         this.setCliArgs({
             json: this.json,
+            full: this.full,
+            human: this.human,
             port: this.port ?? '',
             query,
             url: this.url ?? '',
@@ -447,7 +464,10 @@ class TraceCommand extends ProteumCommand {
 
     public port = Option.String('--port', { description: 'Override the router port used to query the running dev server.' });
     public url = Option.String('--url', { description: 'Override the full base URL used to query the running dev server.' });
-    public json = Option.Boolean('--json', false, { description: 'Print JSON output.' });
+    public json = Option.Boolean('--json', false, { description: 'Compatibility flag; compact JSON is the default output.' });
+    public full = Option.Boolean('--full', false, { description: 'Print the full trace response.' });
+    public events = Option.Boolean('--events', false, { description: 'Include full event, call, SQL, and payload detail.' });
+    public human = Option.Boolean('--human', false, { description: 'Print the legacy human-readable trace report.' });
     public capture = Option.String('--capture', { description: 'Capture mode used by `proteum trace arm`.' });
     public output = Option.String('--output', { description: 'Output filepath used by `proteum trace export`.' });
     public args = Option.Rest();
@@ -461,6 +481,9 @@ class TraceCommand extends ProteumCommand {
             port: this.port ?? '',
             url: this.url ?? '',
             json: this.json,
+            full: this.full,
+            events: this.events,
+            human: this.human,
             capture: this.capture ?? '',
             output: this.output ?? '',
         });
@@ -526,7 +549,9 @@ class DiagnoseCommand extends ProteumCommand {
 
     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 json = Option.Boolean('--json', false, { description: 'Compatibility flag; compact JSON is the default output.' });
+    public full = Option.Boolean('--full', false, { description: 'Print the full diagnose payload.' });
+    public human = Option.Boolean('--human', false, { description: 'Print the legacy human-readable report.' });
     public hit = Option.String('--hit', { description: 'Issue one HTTP request before diagnosing. Defaults to the target path when it starts with /.' });
     public method = Option.String('--method', { description: 'HTTP method used with `--hit`.' });
     public dataJson = Option.String('--data-json', { description: 'JSON request body used with `--hit`.' });
@@ -547,6 +572,8 @@ class DiagnoseCommand extends ProteumCommand {
             dataJson: this.dataJson ?? '',
             hit: this.hit ?? '',
             json: this.json,
+            full: this.full,
+            human: this.human,
             logsLevel: this.logsLevel ?? '',
             logsLimit: this.logsLimit ?? '',
             method: this.method ?? '',
@@ -568,7 +595,9 @@ class PerfCommand extends ProteumCommand {
 
     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 json = Option.Boolean('--json', false, { description: 'Compatibility flag; compact JSON is the default output.' });
+    public full = Option.Boolean('--full', false, { description: 'Print the full perf payload.' });
+    public human = Option.Boolean('--human', false, { description: 'Print the legacy human-readable report.' });
     public since = Option.String('--since', { description: 'Window used by `top` and `memory`, for example `today`, `yesterday`, or `1h`.' });
     public baseline = Option.String('--baseline', { description: 'Baseline window used by `compare`.' });
     public target = Option.String('--target', { description: 'Target window used by `compare`.' });
@@ -584,6 +613,8 @@ class PerfCommand extends ProteumCommand {
             baseline: this.baseline ?? '',
             groupBy: this.groupBy ?? '',
             json: this.json,
+            full: this.full,
+            human: this.human,
             limit: this.limit ?? '',
             port: this.port ?? '',
             since: this.since ?? '',
@@ -596,6 +627,54 @@ class PerfCommand extends ProteumCommand {
     }
 }
 
+class RuntimeCommand extends ProteumCommand {
+    public static paths = [['runtime']];
+
+    public static usage = buildUsage('runtime');
+
+    public full = Option.Boolean('--full', false, { description: 'Print full tracked-session and health detail.' });
+    public sessionFile = Option.String('--session-file', {
+        description: 'Inspect one explicit dev session file instead of the app registry.',
+    });
+    public args = Option.Rest();
+
+    public async execute() {
+        const [action = 'status'] = this.args;
+
+        this.setCliArgs({
+            action,
+            full: this.full,
+            sessionFile: this.sessionFile ?? '',
+        });
+
+        await runCommandModule(() => import('../commands/runtime'));
+    }
+}
+
+class McpCommand extends ProteumCommand {
+    public static paths = [['mcp']];
+
+    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 url = Option.String('--url', { description: 'Use a running Proteum dev server as the live runtime data source.' });
+    public legacyArgs = Option.Rest();
+
+    public async execute() {
+        assertNoLegacyArgs('mcp', this.legacyArgs);
+        this.setCliArgs({
+            sessionFile: this.sessionFile ?? '',
+            url: this.url ?? '',
+            workdir: this.cwd ?? '',
+        });
+
+        await runCommandModule(() => import('../commands/mcp'));
+    }
+}
+
 class VerifyCommand extends ProteumCommand {
     public static paths = [['verify']];
 
@@ -672,6 +751,8 @@ export const registeredCommands = {
     orient: OrientCommand,
     diagnose: DiagnoseCommand,
     perf: PerfCommand,
+    runtime: RuntimeCommand,
+    mcp: McpCommand,
     trace: TraceCommand,
     command: CommandCommand,
     session: SessionCommand,
@@ -705,6 +786,8 @@ export const createCli = (version: string) => {
     clipanion.register(OrientCommand);
     clipanion.register(DiagnoseCommand);
     clipanion.register(PerfCommand);
+    clipanion.register(RuntimeCommand);
+    clipanion.register(McpCommand);
     clipanion.register(TraceCommand);
     clipanion.register(CommandCommand);
     clipanion.register(SessionCommand);

package/cli/utils/agentOutput.ts

@@ -0,0 +1,46 @@
+/*----------------------------------
+- TYPES
+----------------------------------*/
+
+export type TAgentNextAction = {
+    command: string;
+    label: string;
+    reason?: string;
+};
+
+export type TAgentOmittedDetail = {
+    command: string;
+    reason: string;
+};
+
+export type TAgentResponse<TData extends object> = {
+    ok: true;
+    format: 'proteum-agent-v1';
+    summary: string;
+    data: TData;
+    nextActions?: TAgentNextAction[];
+    omitted?: TAgentOmittedDetail[];
+    fullDetailCommand?: string;
+};
+
+/*----------------------------------
+- HELPERS
+----------------------------------*/
+
+export const truncateForAgent = (value: string, max = 220) => (value.length <= max ? value : `${value.slice(0, max)}...`);
+
+export const compactList = <TValue>(values: TValue[], limit: number) => values.slice(0, Math.max(0, limit));
+
+export const printJson = (value: object) => {
+    console.log(JSON.stringify(value, null, 2));
+};
+
+export const printAgentResponse = <TData extends object>(response: Omit<TAgentResponse<TData>, 'format' | 'ok'>) => {
+    printJson({
+        ok: true,
+        format: 'proteum-agent-v1',
+        ...response,
+    });
+};
+
+export const quoteCommandArgument = (value: string) => JSON.stringify(value);