proteum 2.2.9 → 2.4.1

package/cli/commands/dev.ts

@@ -28,19 +28,24 @@ import { clearInteractiveConsole } from '../presentation/welcome';
 import { renderWarning } from '../presentation/ink';
 import {
     createDevSessionRecord,
-    inspectDevSessionFile,
     listDevSessionInspections,
+    prepareDevSessionStart,
     removeDevSessionRecord,
     removeDevSessionRecordSync,
     resolveDevSessionFilePath,
     stopDevSessionFile,
     updateDevSessionRecord,
+    writeDevSessionRecord,
+    writeMachineDevSessionRecord,
     type TDevSessionInspection,
     type TStopDevSessionResult,
 } from '../runtime/devSessions';
 import { resolveFrameworkInstallInfo } from '../paths';
 import { logVerbose } from '../runtime/verbose';
+import { ensureMachineMcpDaemonProcess } from '../runtime/mcpDaemon';
+import { inspectDevPort, type TDevPortInspection } from '../runtime/ports';
 import { configureProjectAgentInstructions, resolveProjectAgentMonorepoRoot } from '../utils/agents';
+import { quoteCommandArgument } from '../utils/agentOutput';
 
 // Core
 import { app, App } from '../app';
@@ -335,6 +340,40 @@ const describeStopResult = (result: TStopDevSessionResult) => {
         .join(' | ');
 };
 
+const describeBlockingDevSession = (inspection: TDevSessionInspection) => {
+    if (!inspection.record) {
+        return [
+            '- invalid session',
+            inspection.sessionFilePath,
+            inspection.parseError || 'Unreadable session file.',
+        ]
+            .filter(Boolean)
+            .join(' | ');
+    }
+
+    const publicUrl = inspection.record.publicUrl || `http://localhost:${inspection.record.routerPort}`;
+
+    return [
+        `- pid ${inspection.record.pid}`,
+        `port ${inspection.record.routerPort}`,
+        publicUrl,
+        `session ${inspection.sessionFilePath}`,
+    ].join(' | ');
+};
+
+const createBlockingDevSessionMessage = (blocking: TDevSessionInspection[]) => {
+    const firstSessionFilePath = blocking[0]?.sessionFilePath || '<session-file>';
+
+    return [
+        `A Proteum dev session is already running for ${app.paths.root}.`,
+        'Stop the existing session before starting another server in the same worktree:',
+        ...blocking.map(describeBlockingDevSession),
+        '',
+        `Run: npx proteum dev stop --session-file ${quoteCommandArgument(firstSessionFilePath)}`,
+        'Then start dev again with the intended session file and port.',
+    ].join('\n');
+};
+
 const printJson = (payload: unknown) => {
     process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
 };
@@ -400,38 +439,120 @@ const runStopCommand = async () => {
 
 const ensureDevSessionSlot = async () => {
     const sessionFilePath = getResolvedDevSessionFilePath();
-    const existingInspection = await inspectDevSessionFile(sessionFilePath);
-
-    if (existingInspection?.record && existingInspection.live && existingInspection.record.pid !== process.pid) {
-        if (cli.args.replaceExisting !== true) {
-            throw new Error(
-                `A Proteum dev session is already registered at ${sessionFilePath} (pid ${existingInspection.record.pid}, port ${existingInspection.record.routerPort}). ` +
-                    'Use `proteum dev stop` or restart with `proteum dev --replace-existing`.',
-            );
-        }
+    const startPreparation = await prepareDevSessionStart({
+        appRoot: app.paths.root,
+        replaceExisting: cli.args.replaceExisting === true,
+        sessionFilePath,
+    });
 
-        const stopResult = await stopDevSessionFile(sessionFilePath);
-        if (!stopResult.stopped) {
-            throw new Error(`Could not stop the existing Proteum dev session registered at ${sessionFilePath}.`);
-        }
-    } else if (existingInspection) {
-        await stopDevSessionFile(sessionFilePath);
+    if (startPreparation.blocking.length > 0) {
+        throw new Error(createBlockingDevSessionMessage(startPreparation.blocking));
     }
 
     currentDevSessionFilePath = sessionFilePath;
     registerDevSessionExitCleanup();
-    await fs.ensureDir(path.dirname(sessionFilePath));
-    await fs.writeJson(
+    const sessionRecord = createDevSessionRecord({
+        appRoot: app.paths.root,
+        port: app.env.router.port,
         sessionFilePath,
-        createDevSessionRecord({
-            appRoot: app.paths.root,
-            port: app.env.router.port,
-            sessionFilePath,
-        }),
-        { spaces: 2 },
-    );
+    });
+
+    await writeDevSessionRecord(sessionRecord);
+    await writeMachineDevSessionRecord(sessionRecord);
 
     logVerbose(`Registered Proteum dev session at ${sessionFilePath}.`);
+    if (startPreparation.cleaned.length > 0) {
+        logVerbose(
+            `Cleaned ${startPreparation.cleaned.length} stale Proteum dev session file${startPreparation.cleaned.length === 1 ? '' : 's'}.`,
+        );
+    }
+    if (startPreparation.replaced) {
+        logVerbose(`Replaced Proteum dev session at ${startPreparation.replaced.sessionFilePath}.`);
+    }
+};
+
+const ensureMachineMcpDaemonForDev = async () => {
+    try {
+        const result = await ensureMachineMcpDaemonProcess({ coreRoot: cli.paths.core.root });
+        const record = result.inspection.record;
+        if (!record) return;
+
+        logVerbose(
+            result.started
+                ? `Started Proteum machine MCP daemon at ${record.mcpUrl}.`
+                : `Proteum machine MCP daemon already running at ${record.mcpUrl}.`,
+        );
+    } catch (error) {
+        console.warn(
+            `Warning: Proteum could not ensure the machine MCP daemon. ${
+                error instanceof Error ? error.message : String(error)
+            }`,
+        );
+    }
+};
+
+const describeDevPortBlocker = (inspection: TDevPortInspection) => {
+    const lines = [
+        `Proteum cannot start this dev server on port ${inspection.router.port}.`,
+        `Router port ${inspection.router.port}: ${inspection.router.available ? 'free' : 'occupied'}.`,
+        `HMR port ${inspection.hmr.port}: ${inspection.hmr.available ? 'free' : 'occupied'}.`,
+    ];
+
+    if (!inspection.router.available && inspection.router.proteum && inspection.router.matchesApp) {
+        lines.push(
+            `The router port is already serving this Proteum app${inspection.router.app?.appRoot ? ` from ${inspection.router.app.appRoot}` : ''}.`,
+        );
+        lines.push('Next action: run `npx proteum runtime status`, use or stop the existing runtime, then start one tracked dev session.');
+        lines.push('Do not start a second dev server for the same worktree.');
+    } else if (!inspection.router.available && inspection.router.proteum) {
+        lines.push(
+            `The router port is already serving ${inspection.router.app?.identifier || inspection.router.app?.name || 'another Proteum app'}${inspection.router.app?.appRoot ? ` from ${inspection.router.app.appRoot}` : ''}.`,
+        );
+        lines.push(
+            inspection.recommendedPort
+                ? `Next action: npx proteum dev --session-file var/run/proteum/dev/agents/<task>.json --port ${inspection.recommendedPort}`
+                : 'Next action: choose a free router/HMR port pair, then rerun proteum dev with --port <free-port>.',
+        );
+    } else if (!inspection.router.available) {
+        lines.push('The router port is occupied by a non-Proteum or unrecognized process.');
+        lines.push(
+            inspection.recommendedPort
+                ? `Next action: npx proteum dev --session-file var/run/proteum/dev/agents/<task>.json --port ${inspection.recommendedPort}`
+                : 'Next action: choose a free router/HMR port pair, then rerun proteum dev with --port <free-port>.',
+        );
+    } else if (!inspection.hmr.available) {
+        lines.push('The HMR port is occupied.');
+        lines.push(
+            inspection.recommendedPort
+                ? `Next action: npx proteum dev --session-file var/run/proteum/dev/agents/<task>.json --port ${inspection.recommendedPort}`
+                : 'Next action: choose a free router/HMR port pair, then rerun proteum dev with --port <free-port>.',
+        );
+    }
+
+    lines.push('Do not inspect page bodies to identify the owner; use `npx proteum runtime status` for compact port/runtime state.');
+
+    return lines.join('\n');
+};
+
+const ensureConfiguredDevPortsAvailable = async () => {
+    const inspection = await inspectDevPort({
+        appRoot: app.paths.root,
+        port: app.env.router.port,
+    });
+
+    if (inspection.canStartOnConfiguredPort) return;
+
+    if (cli.args.replaceExisting === true) {
+        const requestedSessionFilePath = getResolvedDevSessionFilePath();
+        const [requestedSession] = await listDevSessionInspections({
+            appRoot: app.paths.root,
+            sessionFilePath: requestedSessionFilePath,
+        });
+
+        if (requestedSession?.record && requestedSession.live) return;
+    }
+
+    throw new Error(describeDevPortBlocker(inspection));
 };
 
 async function startApp(app: App) {
@@ -757,8 +878,10 @@ const createIndexedSourceWatching = ({
 
 const runDevLoop = async () => {
     devSessionStopping = false;
+    await ensureConfiguredDevPortsAvailable();
     clearInteractiveConsole();
     await ensureDevSessionSlot();
+    await ensureMachineMcpDaemonForDev();
     const proteumInstall = resolveFrameworkInstallInfo({
         appRoot: app.paths.root,
         framework: cli.paths.framework,

package/cli/commands/diagnose.ts

@@ -12,6 +12,7 @@ import type { TRequestTraceErrorResponse, TRequestTraceArmResponse } from '../..
 import type { TDevSessionErrorResponse, TDevSessionStartResponse } from '../../common/dev/session';
 import { summarizeTraceForDiagnose } from '@common/dev/inspection';
 import { readProteumManifest } from '../compiler/common/proteumManifest';
+import { compactList, printAgentResponse, printJson, quoteCommandArgument, truncateForAgent } from '../utils/agentOutput';
 
 const normalizeBaseUrl = (value: string) => value.replace(/\/+$/, '');
 const truncate = (value: string, max = 160) => (value.length <= max ? value : `${value.slice(0, max)}...`);
@@ -186,6 +187,7 @@ const renderOrientation = (response: TDiagnoseResponse) =>
         : [
               'Orientation',
               `- agents=${response.orientation.guidance.agents}`,
+              `- documentation=${response.orientation.guidance.documentation}`,
               `- diagnostics=${response.orientation.guidance.diagnostics}`,
               `- optimizations=${response.orientation.guidance.optimizations}`,
               `- codingStyle=${response.orientation.guidance.codingStyle}`,
@@ -237,6 +239,133 @@ const renderHuman = (manifest: ReturnType<typeof readProteumManifest>, response:
         renderLogs(response.serverLogs),
     ].join('\n');
 
+const compactOwnerMatch = (match: TDiagnoseResponse['owner']['matches'][number]) => ({
+    kind: match.kind,
+    label: match.label,
+    score: match.score,
+    scope: match.scopeLabel,
+    origin: match.originHint,
+    source: match.source,
+});
+
+const compactDiagnostic = (diagnostic: TDiagnoseResponse['doctor']['diagnostics'][number]) => ({
+    level: diagnostic.level,
+    code: diagnostic.code,
+    message: truncateForAgent(diagnostic.message),
+    filepath: diagnostic.filepath,
+    sourceLocation: diagnostic.sourceLocation,
+    fixHint: diagnostic.fixHint ? truncateForAgent(diagnostic.fixHint) : undefined,
+});
+
+const compactRequest = (request: TDiagnoseResponse['request']) =>
+    request
+        ? {
+              id: request.id,
+              method: request.method,
+              path: request.path,
+              statusCode: request.statusCode,
+              durationMs: request.durationMs,
+              capture: request.capture,
+              user: request.user,
+              errorMessage: request.errorMessage,
+              counts: {
+                  calls: request.calls.length,
+                  events: request.events.length,
+                  sqlQueries: request.sqlQueries.length,
+                  droppedEvents: request.droppedEvents,
+              },
+          }
+        : undefined;
+
+const buildDiagnoseFullDetailCommand = ({
+    hitPath,
+    query,
+}: {
+    hitPath: string;
+    query: string;
+}) =>
+    [
+        'proteum diagnose',
+        quoteCommandArgument(query),
+        hitPath ? `--hit ${quoteCommandArgument(hitPath)}` : '',
+        typeof cli.args.port === 'string' && cli.args.port ? `--port ${cli.args.port}` : '',
+        typeof cli.args.url === 'string' && cli.args.url ? `--url ${quoteCommandArgument(cli.args.url)}` : '',
+        '--full',
+    ]
+        .filter(Boolean)
+        .join(' ');
+
+const printCompactDiagnose = ({
+    hitPath,
+    query,
+    response,
+}: {
+    hitPath: string;
+    query: string;
+    response: TDiagnoseResponse;
+}) => {
+    const request = compactRequest(response.request);
+    const traceSummary = summarizeTraceForDiagnose(response.request);
+    const doctorSummary = `${response.doctor.summary.errors} doctor errors/${response.doctor.summary.warnings} warnings`;
+    const contractsSummary = `${response.contracts.summary.errors} contract errors/${response.contracts.summary.warnings} warnings`;
+    const summary = `${response.query || query || 'request'}: ${traceSummary}; ${doctorSummary}; ${contractsSummary}`;
+    const nextActions = response.orientation?.nextSteps || [];
+    const requestId = response.request?.id;
+
+    printAgentResponse({
+        summary,
+        data: {
+            query: response.query,
+            request,
+            owner: {
+                top: response.owner.matches[0] ? compactOwnerMatch(response.owner.matches[0]) : undefined,
+                matches: compactList(response.owner.matches, 4).map(compactOwnerMatch),
+                totalReturned: response.owner.matches.length,
+            },
+            suspects: compactList(response.suspects, 6),
+            chain: compactList(response.chain || [], 8),
+            diagnostics: {
+                doctor: {
+                    summary: response.doctor.summary,
+                    top: compactList(response.doctor.diagnostics, 6).map(compactDiagnostic),
+                    total: response.doctor.diagnostics.length,
+                },
+                contracts: {
+                    summary: response.contracts.summary,
+                    top: compactList(response.contracts.diagnostics, 6).map(compactDiagnostic),
+                    total: response.contracts.diagnostics.length,
+                },
+            },
+            logs: compactList(response.serverLogs.logs, 10).map((entry) => ({
+                level: entry.level,
+                time: entry.time,
+                text: truncateForAgent(entry.text),
+            })),
+            instructions: response.orientation
+                ? {
+                      mustRead: [...new Set([response.orientation.guidance.agents, ...response.orientation.guidance.areaAgents])],
+                      documentation: response.orientation.guidance.documentation,
+                      diagnostics: response.orientation.guidance.diagnostics,
+                      codingStyle: response.orientation.guidance.codingStyle,
+                      optimizations: response.orientation.guidance.optimizations,
+                  }
+                : undefined,
+        },
+        nextActions,
+        fullDetailCommand: buildDiagnoseFullDetailCommand({ hitPath, query }),
+        omitted: [
+            ...(requestId
+                ? [
+                      {
+                          reason: 'Full request events, API call payloads, and SQL text are omitted from the default diagnose response.',
+                          command: `proteum trace show ${quoteCommandArgument(requestId)} --events`,
+                      },
+                  ]
+                : []),
+        ],
+    });
+};
+
 const resolveManifest = async () => {
     try {
         return readProteumManifest(cli.paths.appRoot);
@@ -258,7 +387,6 @@ export const run = async () => {
     const method = typeof cli.args.method === 'string' && cli.args.method ? cli.args.method.trim().toUpperCase() : 'GET';
     const logsLevel = typeof cli.args.logsLevel === 'string' && cli.args.logsLevel ? cli.args.logsLevel.trim() : 'warn';
     const logsLimit = typeof cli.args.logsLimit === 'string' && cli.args.logsLimit ? cli.args.logsLimit.trim() : '40';
-    const shouldPrintJson = cli.args.json === true;
     const hitPath = hit || (target.startsWith('/') ? target : '');
     const query = target || hitPath;
     let parsedDataJson: unknown;
@@ -308,11 +436,16 @@ export const run = async () => {
     const diagnose = await requestJson<TDiagnoseResponse>(
         `/__proteum/diagnose?${new URLSearchParams(diagnoseRequest).toString()}`,
     );
-    if (shouldPrintJson) {
-        console.log(JSON.stringify(diagnose.body, null, 2));
+    if (cli.args.full === true) {
+        printJson(diagnose.body);
+        return;
+    }
+
+    if (cli.args.human === true) {
+        const manifest = await resolveManifest();
+        console.log(renderHuman(manifest, diagnose.body));
         return;
     }
 
-    const manifest = await resolveManifest();
-    console.log(renderHuman(manifest, diagnose.body));
+    printCompactDiagnose({ hitPath, query, response: diagnose.body });
 };

package/cli/commands/doctor.ts

@@ -3,8 +3,9 @@ import Compiler from '../compiler';
 import { readProteumManifest } from '../compiler/common/proteumManifest';
 import { buildContractsDoctorResponse } from '@common/dev/contractsDoctor';
 import { buildDoctorResponse, renderDoctorHuman, renderDoctorResponseHuman } from '@common/dev/diagnostics';
+import { compactList, printAgentResponse, printJson, truncateForAgent } from '../utils/agentOutput';
 
-const allowedDoctorArgs = new Set(['contracts', 'json', 'strict']);
+const allowedDoctorArgs = new Set(['contracts', 'full', 'human', 'json', 'strict']);
 
 const validateDoctorArgs = () => {
     const enabledArgs = Object.entries(cli.args)
@@ -20,6 +21,15 @@ const validateDoctorArgs = () => {
     }
 };
 
+const compactDiagnostic = (diagnostic: ReturnType<typeof buildDoctorResponse>['diagnostics'][number]) => ({
+    level: diagnostic.level,
+    code: diagnostic.code,
+    message: truncateForAgent(diagnostic.message),
+    filepath: diagnostic.filepath,
+    sourceLocation: diagnostic.sourceLocation,
+    fixHint: diagnostic.fixHint ? truncateForAgent(diagnostic.fixHint) : undefined,
+});
+
 export const run = async (): Promise<void> => {
     validateDoctorArgs();
 
@@ -32,9 +42,9 @@ export const run = async (): Promise<void> => {
             ? buildContractsDoctorResponse(manifest, cli.args.strict === true)
             : buildDoctorResponse(manifest, cli.args.strict === true);
 
-    if (cli.args.json === true) {
-        console.log(JSON.stringify(response, null, 2));
-    } else {
+    if (cli.args.full === true) {
+        printJson(response);
+    } else if (cli.args.human === true) {
         console.log(
             cli.args.contracts === true
                 ? renderDoctorResponseHuman({
@@ -45,6 +55,16 @@ export const run = async (): Promise<void> => {
                   })
                 : renderDoctorHuman(manifest, cli.args.strict === true),
         );
+    } else {
+        printAgentResponse({
+            summary: `${cli.args.contracts === true ? 'Doctor contracts' : 'Doctor'}: ${response.summary.errors} errors, ${response.summary.warnings} warnings`,
+            data: {
+                summary: response.summary,
+                diagnostics: compactList(response.diagnostics, 10).map(compactDiagnostic),
+                totalDiagnostics: response.diagnostics.length,
+            },
+            fullDetailCommand: `proteum doctor${cli.args.contracts === true ? ' --contracts' : ''} --full`,
+        });
     }
 
     if (cli.args.strict === true && response.diagnostics.length > 0) {

package/cli/commands/explain.ts

@@ -2,14 +2,16 @@ import cli from '..';
 import Compiler from '../compiler';
 import { readProteumManifest } from '../compiler/common/proteumManifest';
 import {
+    buildExplainSummaryItems,
     explainSectionNames,
     pickExplainManifestSections,
     renderExplainHuman,
     type TExplainSectionName,
 } from '@common/dev/diagnostics';
 import { explainOwner } from '@common/dev/inspection';
+import { compactList, printAgentResponse, printJson, quoteCommandArgument } from '../utils/agentOutput';
 
-const allowedExplainArgs = new Set(['json', 'all', ...explainSectionNames]);
+const allowedExplainArgs = new Set(['json', 'all', 'full', 'human', 'manifest', ...explainSectionNames]);
 
 const validateExplainArgs = () => {
     const enabledArgs = Object.entries(cli.args)
@@ -31,6 +33,122 @@ const getSelectedSections = (): TExplainSectionName[] => {
     return explainSectionNames.filter((sectionName) => cli.args[sectionName] === true);
 };
 
+const compactOwnerMatch = (match: ReturnType<typeof explainOwner>['matches'][number]) => ({
+    kind: match.kind,
+    label: match.label,
+    score: match.score,
+    scope: match.scopeLabel,
+    origin: match.originHint,
+    source: match.source,
+});
+
+const hasExplicitDetailSelection = () => cli.args.full === true || cli.args.manifest === true;
+
+const buildSectionFlagCommand = (selectedSections: TExplainSectionName[]) =>
+    selectedSections.length === explainSectionNames.length
+        ? 'proteum explain --all --full'
+        : `proteum explain ${selectedSections.map((sectionName) => `--${sectionName}`).join(' ')} --full`;
+
+const summarizeSelectedSection = (manifest: ReturnType<typeof readProteumManifest>, sectionName: TExplainSectionName) => {
+    if (sectionName === 'app') return { section: sectionName, count: 1 };
+    if (sectionName === 'conventions')
+        return {
+            section: sectionName,
+            count: manifest.conventions.routeOptionKeys.length + manifest.conventions.reservedRouteOptionKeys.length,
+        };
+    if (sectionName === 'env') return { section: sectionName, count: manifest.env.requiredVariables.length };
+    if (sectionName === 'connected') return { section: sectionName, count: manifest.connectedProjects.length };
+    if (sectionName === 'services')
+        return { section: sectionName, count: manifest.services.app.length + manifest.services.routerPlugins.length };
+    if (sectionName === 'controllers') return { section: sectionName, count: manifest.controllers.length };
+    if (sectionName === 'commands') return { section: sectionName, count: manifest.commands.length };
+    if (sectionName === 'routes') return { section: sectionName, count: manifest.routes.client.length + manifest.routes.server.length };
+    if (sectionName === 'layouts') return { section: sectionName, count: manifest.layouts.length };
+    return { section: sectionName, count: manifest.diagnostics.length };
+};
+
+const printCompactOwner = (ownerQuery: string, response: ReturnType<typeof explainOwner>) => {
+    const topOwner = response.matches[0];
+
+    printAgentResponse({
+        summary: topOwner
+            ? `${ownerQuery} -> ${topOwner.kind} ${topOwner.label} (${topOwner.scopeLabel})`
+            : `${ownerQuery} -> no manifest owner matched`,
+        data: {
+            query: ownerQuery,
+            normalizedQuery: response.normalizedQuery,
+            top: topOwner ? compactOwnerMatch(topOwner) : undefined,
+            matches: compactList(response.matches, 6).map(compactOwnerMatch),
+            totalReturned: response.matches.length,
+        },
+        nextActions: [
+            {
+                label: 'Orient',
+                command: `proteum orient ${quoteCommandArgument(ownerQuery)}`,
+                reason: 'Resolve the owner together with the relevant instruction files and next command.',
+            },
+        ],
+        fullDetailCommand: `proteum explain owner ${quoteCommandArgument(ownerQuery)} --full`,
+    });
+};
+
+const printCompactExplain = (manifest: ReturnType<typeof readProteumManifest>, selectedSections: TExplainSectionName[] = []) => {
+    const errors = manifest.diagnostics.filter((diagnostic) => diagnostic.level === 'error').length;
+    const warnings = manifest.diagnostics.filter((diagnostic) => diagnostic.level === 'warning').length;
+    const requiredEnvProvided = manifest.env.requiredVariables.filter((variable) => variable.provided).length;
+    const hasSelectedSections = selectedSections.length > 0;
+    const fullDetailCommand = hasSelectedSections ? buildSectionFlagCommand(selectedSections) : 'proteum explain --manifest';
+
+    printAgentResponse({
+        summary: hasSelectedSections
+            ? `${manifest.app.identity.identifier}: summarized ${selectedSections.join(', ')} sections; use --full for raw section arrays`
+            : `${manifest.app.identity.identifier}: ${manifest.controllers.length} controllers, ${manifest.routes.client.length + manifest.routes.server.length} routes, ${errors} errors, ${warnings} warnings`,
+        data: {
+            app: {
+                root: manifest.app.root,
+                coreRoot: manifest.app.coreRoot,
+                identifier: manifest.app.identity.identifier,
+                name: manifest.app.identity.name,
+            },
+            counts: {
+                commands: manifest.commands.length,
+                connectedProjects: manifest.connectedProjects.length,
+                controllers: manifest.controllers.length,
+                diagnostics: manifest.diagnostics.length,
+                layouts: manifest.layouts.length,
+                routesClient: manifest.routes.client.length,
+                routesServer: manifest.routes.server.length,
+                servicesApp: manifest.services.app.length,
+                servicesRouterPlugins: manifest.services.routerPlugins.length,
+            },
+            diagnostics: { errors, warnings },
+            selectedSections: hasSelectedSections ? selectedSections.map((sectionName) => summarizeSelectedSection(manifest, sectionName)) : undefined,
+            env: {
+                requiredProvided: requiredEnvProvided,
+                requiredTotal: manifest.env.requiredVariables.length,
+                routerPort: manifest.env.resolved.routerPort,
+            },
+            summaryItems: buildExplainSummaryItems(manifest),
+        },
+        nextActions: [
+            {
+                label: 'Orient Target',
+                command: 'proteum orient <route|file|controller|error>',
+                reason: 'Use orient for task-specific owner, instruction, and next-command routing.',
+            },
+        ],
+        fullDetailCommand,
+        omitted: [
+            {
+                reason: hasSelectedSections
+                    ? 'Selected manifest sections are summarized by default to avoid large route/controller dumps.'
+                    : 'Full manifest sections are omitted from the default agent summary.',
+                command: fullDetailCommand,
+            },
+        ],
+    });
+};
+
 export const run = async (): Promise<void> => {
     validateExplainArgs();
 
@@ -42,8 +160,13 @@ export const run = async (): Promise<void> => {
 
     if (ownerQuery) {
         const response = explainOwner(manifest, ownerQuery);
-        if (cli.args.json === true) {
-            console.log(JSON.stringify(response, null, 2));
+        if (cli.args.full === true || cli.args.manifest === true) {
+            printJson(response);
+            return;
+        }
+
+        if (cli.args.human !== true) {
+            printCompactOwner(ownerQuery, response);
             return;
         }
 
@@ -64,10 +187,15 @@ export const run = async (): Promise<void> => {
 
     const selectedSections = getSelectedSections();
 
-    if (cli.args.json === true) {
-        console.log(JSON.stringify(pickExplainManifestSections(manifest, selectedSections), null, 2));
+    if (hasExplicitDetailSelection()) {
+        printJson(pickExplainManifestSections(manifest, cli.args.manifest === true ? [...explainSectionNames] : selectedSections));
+        return;
+    }
+
+    if (cli.args.human === true) {
+        console.log(renderExplainHuman(manifest, selectedSections));
         return;
     }
 
-    console.log(renderExplainHuman(manifest, selectedSections));
+    printCompactExplain(manifest, selectedSections);
 };