proteum 2.2.9 → 2.3.0

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);

package/cli/utils/agents.ts

@@ -23,6 +23,7 @@ type TConfigureProjectAgentInstructionsArgs = {
 type TAgentInstructionDefinition = {
     projectPath: string;
     ensureParentDir?: boolean;
+    content?: 'router' | 'source';
 };
 
 type TEnsureInstructionFilesResult = {
@@ -60,33 +61,39 @@ const managedInstructionSectionEnd = '<!-- proteum-instructions:end -->';
 const managedInstructionSectionIntro = 'This section is managed by `proteum configure agents`.';
 
 const sharedRootDocumentInstructionDefinitions: TAgentInstructionDefinition[] = [
-    { projectPath: 'CODING_STYLE.md' },
-    { projectPath: 'diagnostics.md' },
-    { projectPath: 'optimizations.md' },
+    { projectPath: 'CODING_STYLE.md', content: 'source' },
+    { projectPath: 'diagnostics.md', content: 'source' },
+    { projectPath: 'optimizations.md', content: 'source' },
 ];
 
-const sharedAreaAgentInstructionDefinitions: TAgentInstructionDefinition[] = [
-    { projectPath: path.join('client', 'AGENTS.md') },
-    { projectPath: path.join('client', 'pages', 'AGENTS.md') },
-    { projectPath: path.join('server', 'services', 'AGENTS.md') },
-    { projectPath: path.join('server', 'routes', 'AGENTS.md') },
-    { projectPath: path.join('tests', 'e2e', 'AGENTS.md') },
+const sharedAppAreaAgentInstructionDefinitions: TAgentInstructionDefinition[] = [
+    { projectPath: path.join('client', 'AGENTS.md'), content: 'source' },
+    { projectPath: path.join('client', 'pages', 'AGENTS.md'), content: 'source' },
+    { projectPath: path.join('server', 'services', 'AGENTS.md'), content: 'source' },
+    { projectPath: path.join('server', 'routes', 'AGENTS.md'), content: 'source' },
+];
+
+const sharedE2eAgentInstructionDefinitions: TAgentInstructionDefinition[] = [
+    { projectPath: path.join('tests', 'e2e', 'AGENTS.md'), ensureParentDir: true, content: 'source' },
+    { projectPath: path.join('tests', 'e2e', 'REAL_WORLD_JOURNEY_TESTS.md'), ensureParentDir: true, content: 'source' },
 ];
 
 const standaloneAppAgentInstructionDefinitions: TAgentInstructionDefinition[] = [
-    { projectPath: 'AGENTS.md' },
+    { projectPath: 'AGENTS.md', content: 'router' },
     ...sharedRootDocumentInstructionDefinitions,
-    ...sharedAreaAgentInstructionDefinitions,
+    ...sharedAppAreaAgentInstructionDefinitions,
+    ...sharedE2eAgentInstructionDefinitions,
 ];
 
 const monorepoAppAgentInstructionDefinitions: TAgentInstructionDefinition[] = [
-    { projectPath: 'AGENTS.md' },
-    ...sharedAreaAgentInstructionDefinitions,
+    { projectPath: 'AGENTS.md', content: 'router' },
+    ...sharedAppAreaAgentInstructionDefinitions,
 ];
 
 const monorepoRootAgentInstructionDefinitions: TAgentInstructionDefinition[] = [
-    { projectPath: 'AGENTS.md' },
+    { projectPath: 'AGENTS.md', content: 'router' },
     ...sharedRootDocumentInstructionDefinitions,
+    ...sharedE2eAgentInstructionDefinitions,
 ];
 
 const legacyProjectInstructionGitignoreBlockStart = '# Proteum-managed instruction symlinks';
@@ -163,7 +170,7 @@ export function configureProjectAgentInstructions({
     if (mode === 'monorepo') {
         const retiredAppRootFiles = removeManagedInstructionFiles(
             normalizedAppRoot,
-            sharedRootDocumentInstructionDefinitions,
+            [...sharedRootDocumentInstructionDefinitions, ...sharedE2eAgentInstructionDefinitions],
             '[agents]',
             path.join(coreRoot, 'agents', 'project'),
             {
@@ -174,7 +181,9 @@ export function configureProjectAgentInstructions({
     }
 
     const appGitignoreCleanupInstructions =
-        mode === 'monorepo' ? [...appInstructions, ...sharedRootDocumentInstructionDefinitions] : appInstructions;
+        mode === 'monorepo'
+            ? [...appInstructions, ...sharedRootDocumentInstructionDefinitions, ...sharedE2eAgentInstructionDefinitions]
+            : appInstructions;
 
     if (
         !dryRun &&
@@ -299,13 +308,21 @@ function ensureInstructionFiles(
             continue;
         }
 
+        const instructionContent = renderProjectInstructionContent({
+            instructionDefinition,
+            managedSourceRoot,
+            managedSectionContent,
+        });
         const existingState = inspectExistingPath({
             managedSourceRoot,
             projectFilepath,
         });
 
         if (existingState.kind === 'file') {
-            const nextContent = upsertManagedInstructionSection(existingState.content, managedSectionContent);
+            const nextContent =
+                instructionDefinition.content === 'source'
+                    ? instructionContent
+                    : upsertManagedInstructionSection(existingState.content, instructionContent);
             if (nextContent === existingState.content) {
                 result.skipped.push(relativeProjectPath);
                 continue;
@@ -320,7 +337,7 @@ function ensureInstructionFiles(
         if (existingState.kind === 'managed-different') {
             if (!dryRun) {
                 fs.removeSync(projectFilepath);
-                fs.writeFileSync(projectFilepath, managedSectionContent);
+                fs.writeFileSync(projectFilepath, instructionContent);
             }
             result.updated.push(relativeProjectPath);
             logVerbose(`${logPrefix} Updated ${relativeProjectPath}`);
@@ -336,14 +353,14 @@ function ensureInstructionFiles(
         if (existingState.kind === 'blocked') {
             if (!dryRun) {
                 fs.removeSync(projectFilepath);
-                fs.writeFileSync(projectFilepath, managedSectionContent);
+                fs.writeFileSync(projectFilepath, instructionContent);
             }
             result.overwritten.push(relativeProjectPath);
             logVerbose(`${logPrefix} Replaced ${relativeProjectPath}`);
             continue;
         }
 
-        if (!dryRun) fs.writeFileSync(projectFilepath, managedSectionContent);
+        if (!dryRun) fs.writeFileSync(projectFilepath, instructionContent);
         result.created.push(relativeProjectPath);
         logVerbose(`${logPrefix} Created ${relativeProjectPath}`);
     }
@@ -482,52 +499,102 @@ function mergeInstructionResults(
     result.blocked.push(...next.blocked.map((entry) => formatResultPath(rootDir, entry)));
 }
 
-function renderEmbeddedProjectInstructions({ coreRoot }: TProjectInstructionArgs) {
-    const agentSourceRoot = path.join(coreRoot, 'agents', 'project');
-    if (!fs.existsSync(agentSourceRoot)) throw new Error(`Missing project instruction source root: ${agentSourceRoot}`);
+function renderProjectInstructionContent({
+    instructionDefinition,
+    managedSourceRoot,
+    managedSectionContent,
+}: {
+    instructionDefinition: TAgentInstructionDefinition;
+    managedSourceRoot: string;
+    managedSectionContent: string;
+}) {
+    if (instructionDefinition.content !== 'source') return managedSectionContent;
+
+    return renderSingleProjectInstruction({
+        managedSourceRoot,
+        projectPath: instructionDefinition.projectPath,
+    });
+}
 
-    const sourceFiles = collectMarkdownFiles(agentSourceRoot).sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+function renderSingleProjectInstruction({
+    managedSourceRoot,
+    projectPath,
+}: {
+    managedSourceRoot: string;
+    projectPath: string;
+}) {
+    const sourceFilepath = path.join(managedSourceRoot, projectPath);
+    if (!fs.existsSync(sourceFilepath)) throw new Error(`Missing project instruction source file: ${sourceFilepath}`);
+
+    const content = fs.readFileSync(sourceFilepath, 'utf8');
+    const demotedContent = demoteMarkdownHeadings(content).trim();
     const lines = [
         managedInstructionSectionHeader,
         managedInstructionSectionStart,
         '',
         managedInstructionSectionIntro,
         '',
+        `## Source: ${normalizeProjectPathForGitignore(projectPath)}`,
+        '',
     ];
 
-    for (const sourceFile of sourceFiles) {
-        const content = fs.readFileSync(sourceFile.filepath, 'utf8');
-        const demotedContent = demoteMarkdownHeadings(content).trim();
-
-        lines.push(`## Source: ${sourceFile.relativePath}`, '');
-        if (demotedContent) lines.push(demotedContent, '');
-    }
-
+    if (demotedContent) lines.push(demotedContent, '');
     lines.push(managedInstructionSectionEnd, '');
 
     return lines.join('\n');
 }
 
-function collectMarkdownFiles(rootDir: string, currentDir = rootDir): { filepath: string; relativePath: string }[] {
-    const files: { filepath: string; relativePath: string }[] = [];
-
-    for (const entry of fs.readdirSync(currentDir, { withFileTypes: true })) {
-        const filepath = path.join(currentDir, entry.name);
-
-        if (entry.isDirectory()) {
-            files.push(...collectMarkdownFiles(rootDir, filepath));
-            continue;
-        }
+function renderEmbeddedProjectInstructions({ coreRoot }: TProjectInstructionArgs) {
+    const agentSourceRoot = path.join(coreRoot, 'agents', 'project');
+    if (!fs.existsSync(agentSourceRoot)) throw new Error(`Missing project instruction source root: ${agentSourceRoot}`);
 
-        if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+    const lines = [
+        managedInstructionSectionHeader,
+        managedInstructionSectionStart,
+        '',
+        managedInstructionSectionIntro,
+        '',
+        '## Agent Routing Contract',
+        '',
+        'Proteum CLI commands are optimized for agents. Do not load the whole instruction corpus up front.',
+        '',
+        '1. Start ambiguous, generated, connected, route, controller, file, or error work with `npx proteum orient <query>`.',
+        '2. Read only the files returned in `mustRead` plus the conditional docs that match the current task.',
+        '3. Use `npx proteum runtime status` before starting a dev server, so an existing tracked session can be reused.',
+        '4. Use `npx proteum diagnose <target>` for request-time issues before raw trace, perf, browser, or broad source search.',
+        '5. Use `--full`, `--manifest`, or `--events` only when a compact CLI response says the omitted detail is needed.',
+        '',
+        '## Always-On Safety',
+        '',
+        '- Never edit generated files under `.proteum`.',
+        '- Never create or edit Prisma migration files manually.',
+        '- Never run schema-mutating SQL such as `ALTER TABLE`, `CREATE TABLE`, `DROP TABLE`, or `CREATE INDEX`.',
+        '- If `schema.prisma` changes, ask the user to run `npx prisma migrate dev --config ./prisma.config.ts --name <migration name>` and wait for `continue` before validation.',
+        '- Do not run `git restore` or `git reset`.',
+        '- Keep `proteum dev` sessions tracked with explicit session files and do not replace another live session.',
+        '',
+        '## Routing Table',
+        '',
+        '- Raw errors, failing requests, traces, perf, or reproduction: read `diagnostics.md`.',
+        '- Implementation edits: read `CODING_STYLE.md` before editing.',
+        '- Client files or pages: read `client/AGENTS.md`; for page route/data/render work also read `client/pages/AGENTS.md`.',
+        '- Server services: read `server/services/AGENTS.md`.',
+        '- Manual server routes: read `server/routes/AGENTS.md`.',
+        '- E2E work: read `tests/e2e/AGENTS.md` and `tests/e2e/REAL_WORLD_JOURNEY_TESTS.md`.',
+        '- Package, runtime, build, or client-performance decisions: read `optimizations.md` after implementation or when explicitly optimizing.',
+        '',
+        '## Canonical Source Map',
+        '',
+        `- Root contract fallback: ${normalizeProjectPathForGitignore(path.join(coreRoot, 'agents', 'project', 'AGENTS.md'))}`,
+        `- Diagnostics fallback: ${normalizeProjectPathForGitignore(path.join(coreRoot, 'agents', 'project', 'diagnostics.md'))}`,
+        `- Optimization fallback: ${normalizeProjectPathForGitignore(path.join(coreRoot, 'agents', 'project', 'optimizations.md'))}`,
+        `- Coding style fallback: ${normalizeProjectPathForGitignore(path.join(coreRoot, 'agents', 'project', 'CODING_STYLE.md'))}`,
+        '',
+    ];
 
-        files.push({
-            filepath,
-            relativePath: normalizeProjectPathForGitignore(path.relative(rootDir, filepath)),
-        });
-    }
+    lines.push(managedInstructionSectionEnd, '');
 
-    return files;
+    return lines.join('\n');
 }
 
 function demoteMarkdownHeadings(content: string) {

package/common/dev/inspection.ts

@@ -1156,12 +1156,20 @@ export const explainOwner = (manifest: TProteumManifest, query: string): TExplai
     const normalizedQuery = normalizeText(query);
     if (!normalizedQuery) return { matches: [], normalizedQuery, query };
 
-    const matches = buildManifestEntries(manifest)
-        .map((entry) => {
-            const { score, matchedOn } = scoreOwnerMatch(query, entry);
-            return score > 0 ? toOwnerMatch(entry, score, matchedOn) : undefined;
-        })
-        .filter((match): match is TExplainOwnerMatch => match !== undefined)
+    const entries = buildManifestEntries(manifest);
+    const scoredMatches =
+        normalizedQuery === '/'
+            ? entries
+                  .filter((entry) => (entry.kind === 'route' || entry.kind === 'controller') && normalizeText(entry.label) === '/')
+                  .map((entry) => toOwnerMatch(entry, 200, ['/']))
+            : entries
+                  .map((entry) => {
+                      const { score, matchedOn } = scoreOwnerMatch(query, entry);
+                      return score > 0 ? toOwnerMatch(entry, score, matchedOn) : undefined;
+                  })
+                  .filter((match): match is TExplainOwnerMatch => match !== undefined);
+
+    const matches = scoredMatches
         .sort((left, right) => right.score - left.score || left.kind.localeCompare(right.kind) || left.label.localeCompare(right.label))
         .slice(0, 12);