proteum 2.2.9 → 2.4.1

package/cli/runtime/ports.ts

@@ -0,0 +1,151 @@
+import net from 'net';
+import path from 'path';
+
+import fs from 'fs-extra';
+import got from 'got';
+
+export type TProteumRuntimePortProbe = {
+    app?: {
+        appRoot?: string;
+        identifier?: string;
+        name?: string;
+    };
+    available: boolean;
+    error?: string;
+    listening: boolean;
+    matchesApp: boolean;
+    port: number;
+    proteum: boolean;
+    publicUrl: string;
+    statusCode?: number;
+};
+
+export type TDevPortInspection = {
+    canStartOnConfiguredPort: boolean;
+    hmr: {
+        available: boolean;
+        port: number;
+    };
+    recommendedPort?: number;
+    router: TProteumRuntimePortProbe;
+};
+
+const normalizePath = (value: string) => {
+    const resolved = path.resolve(value);
+
+    try {
+        return path.normalize(fs.realpathSync(resolved));
+    } catch {
+        return path.normalize(resolved);
+    }
+};
+
+export const isTcpPortAvailable = async (port: number) =>
+    await new Promise<boolean>((resolve) => {
+        const server = net.createServer();
+
+        server.once('error', () => {
+            resolve(false);
+        });
+
+        server.once('listening', () => {
+            server.close(() => resolve(true));
+        });
+
+        server.listen(port, '127.0.0.1');
+    });
+
+export const areTcpPortsAvailable = async (ports: number[]) => {
+    const availability = await Promise.all(ports.map((port) => isTcpPortAvailable(port)));
+    return availability.every(Boolean);
+};
+
+export const findAvailableDevPort = async (startPort: number, { maxOffset = 30 }: { maxOffset?: number } = {}) => {
+    const normalizedStartPort = Math.max(1, Math.floor(startPort));
+
+    for (let port = normalizedStartPort; port <= normalizedStartPort + maxOffset; port += 1) {
+        if (await areTcpPortsAvailable([port, port + 1])) return port;
+    }
+
+    return undefined;
+};
+
+export const probeProteumRuntimePort = async ({
+    appRoot,
+    port,
+}: {
+    appRoot: string;
+    port: number;
+}): Promise<TProteumRuntimePortProbe> => {
+    const publicUrl = `http://localhost:${port}`;
+    const available = await isTcpPortAvailable(port);
+
+    if (available) {
+        return {
+            available: true,
+            listening: false,
+            matchesApp: false,
+            port,
+            proteum: false,
+            publicUrl,
+        };
+    }
+
+    try {
+        const response = await got(`http://127.0.0.1:${port}/__proteum/explain?section=app`, {
+            responseType: 'json',
+            retry: { limit: 0 },
+            throwHttpErrors: false,
+            timeout: { request: 700 },
+        });
+        const body = response.body as { app?: { root?: unknown; identity?: { identifier?: unknown; name?: unknown } } };
+        const root = typeof body.app?.root === 'string' ? body.app.root : undefined;
+        const identifier = typeof body.app?.identity?.identifier === 'string' ? body.app.identity.identifier : undefined;
+        const name = typeof body.app?.identity?.name === 'string' ? body.app.identity.name : undefined;
+        const proteum = response.statusCode < 400 && Boolean(root || identifier || name);
+
+        return {
+            app: proteum ? { appRoot: root, identifier, name } : undefined,
+            available: false,
+            error: proteum ? undefined : `Proteum explain endpoint returned HTTP ${response.statusCode}.`,
+            listening: true,
+            matchesApp: Boolean(root && normalizePath(root) === normalizePath(appRoot)),
+            port,
+            proteum,
+            publicUrl,
+            statusCode: response.statusCode,
+        };
+    } catch (error) {
+        return {
+            available: false,
+            error: error instanceof Error ? error.message : String(error),
+            listening: true,
+            matchesApp: false,
+            port,
+            proteum: false,
+            publicUrl,
+        };
+    }
+};
+
+export const inspectDevPort = async ({
+    appRoot,
+    port,
+}: {
+    appRoot: string;
+    port: number;
+}): Promise<TDevPortInspection> => {
+    const router = await probeProteumRuntimePort({ appRoot, port });
+    const hmr = {
+        port: port + 1,
+        available: await isTcpPortAvailable(port + 1),
+    };
+    const canStartOnConfiguredPort = router.available && hmr.available;
+
+    return {
+        canStartOnConfiguredPort,
+        hmr,
+        recommendedPort: canStartOnConfiguredPort ? port : await findAvailableDevPort(port + 1),
+        router,
+    };
+};

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

@@ -6,12 +6,13 @@
 import fs from 'fs-extra';
 import path from 'path';
 import { logVerbose } from '../runtime/verbose';
+import { createStartDevCommand, findProteumAppRootsUnder, readProteumAppRootSummary } from './appRoots';
 
 /*----------------------------------
 - TYPES
 ----------------------------------*/
 
-type TProjectInstructionArgs = { coreRoot: string };
+type TProjectInstructionArgs = { appRoot?: string; coreRoot: string; includeMonorepoRegistry?: boolean; monorepoRoot?: string };
 type TConfigureProjectAgentInstructionsArgs = {
     appRoot: string;
     coreRoot: string;
@@ -23,6 +24,7 @@ type TConfigureProjectAgentInstructionsArgs = {
 type TAgentInstructionDefinition = {
     projectPath: string;
     ensureParentDir?: boolean;
+    content?: 'router' | 'source';
 };
 
 type TEnsureInstructionFilesResult = {
@@ -60,33 +62,41 @@ 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: 'DOCUMENTATION.md', content: 'source' },
+    { 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 sharedTestAgentInstructionDefinitions: TAgentInstructionDefinition[] = [
+    { projectPath: path.join('tests', 'AGENTS.md'), ensureParentDir: true, content: 'source' },
+    { 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,
+    ...sharedTestAgentInstructionDefinitions,
 ];
 
 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,
+    ...sharedTestAgentInstructionDefinitions,
 ];
 
 const legacyProjectInstructionGitignoreBlockStart = '# Proteum-managed instruction symlinks';
@@ -123,7 +133,20 @@ export function configureProjectAgentInstructions({
         updated: [],
         updatedGitignores: [],
     };
-    const embeddedInstructions = renderEmbeddedProjectInstructions({ coreRoot });
+    const appEmbeddedInstructions = renderEmbeddedProjectInstructions({
+        appRoot: normalizedAppRoot,
+        coreRoot,
+        monorepoRoot: normalizedMonorepoRoot,
+    });
+    const rootEmbeddedInstructions =
+        mode === 'monorepo'
+            ? renderEmbeddedProjectInstructions({
+                  appRoot: normalizedAppRoot,
+                  coreRoot,
+                  includeMonorepoRegistry: true,
+                  monorepoRoot: normalizedMonorepoRoot,
+              })
+            : appEmbeddedInstructions;
 
     if (mode === 'monorepo' && normalizedMonorepoRoot) {
         result.monorepoRoot = normalizedMonorepoRoot;
@@ -134,7 +157,7 @@ export function configureProjectAgentInstructions({
             rootInstructions,
             '[agents]',
             path.join(coreRoot, 'agents', 'project'),
-            embeddedInstructions,
+            rootEmbeddedInstructions,
             {
                 dryRun,
                 overwriteBlockedPaths: normalizedOverwriteBlockedPaths,
@@ -152,7 +175,7 @@ export function configureProjectAgentInstructions({
         appInstructions,
         '[agents]',
         path.join(coreRoot, 'agents', 'project'),
-        embeddedInstructions,
+        appEmbeddedInstructions,
         {
             dryRun,
             overwriteBlockedPaths: normalizedOverwriteBlockedPaths,
@@ -163,7 +186,7 @@ export function configureProjectAgentInstructions({
     if (mode === 'monorepo') {
         const retiredAppRootFiles = removeManagedInstructionFiles(
             normalizedAppRoot,
-            sharedRootDocumentInstructionDefinitions,
+            [...sharedRootDocumentInstructionDefinitions, ...sharedTestAgentInstructionDefinitions],
             '[agents]',
             path.join(coreRoot, 'agents', 'project'),
             {
@@ -174,7 +197,9 @@ export function configureProjectAgentInstructions({
     }
 
     const appGitignoreCleanupInstructions =
-        mode === 'monorepo' ? [...appInstructions, ...sharedRootDocumentInstructionDefinitions] : appInstructions;
+        mode === 'monorepo'
+            ? [...appInstructions, ...sharedRootDocumentInstructionDefinitions, ...sharedTestAgentInstructionDefinitions]
+            : appInstructions;
 
     if (
         !dryRun &&
@@ -299,13 +324,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 +353,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 +369,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 +515,162 @@ 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,
+    });
+}
+
+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 sourceFiles = collectMarkdownFiles(agentSourceRoot).sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+    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 }[] = [];
+function renderMonorepoAppRegistry({
+    appRoot,
+    monorepoRoot,
+}: {
+    appRoot?: string;
+    monorepoRoot?: string;
+}) {
+    if (!monorepoRoot || !appRoot || path.resolve(monorepoRoot) === path.resolve(appRoot)) return [];
+
+    const appRoots = findProteumAppRootsUnder(monorepoRoot);
+    if (appRoots.length === 0) return [];
 
-    for (const entry of fs.readdirSync(currentDir, { withFileTypes: true })) {
-        const filepath = path.join(currentDir, entry.name);
+    const summaries = appRoots.map((candidate) => readProteumAppRootSummary(candidate, monorepoRoot));
 
-        if (entry.isDirectory()) {
-            files.push(...collectMarkdownFiles(rootDir, filepath));
-            continue;
-        }
+    return [
+        '## Known Proteum Apps',
+        '',
+        'This is a monorepo root wrapper. Do not start `npx proteum dev` from this root; start it from one app root below.',
+        '',
+        ...summaries.map((summary) => {
+            const marker = path.resolve(summary.appRoot) === path.resolve(appRoot) ? ' (current configured app)' : '';
+            const port = summary.manifest?.routerPort ? `, default port ${summary.manifest.routerPort}` : '';
+            const command = createStartDevCommand({
+                appRoot: summary.appRoot,
+                baseRoot: monorepoRoot,
+                port: summary.manifest?.routerPort,
+            });
+
+            return `- ${summary.relativeAppRoot || summary.appRoot}${marker}${port}: ${command}`;
+        }),
+        '',
+    ];
+}
 
-        if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+function renderEmbeddedProjectInstructions({ appRoot, coreRoot, includeMonorepoRegistry = false, monorepoRoot }: TProjectInstructionArgs) {
+    const agentSourceRoot = path.join(coreRoot, 'agents', 'project');
+    if (!fs.existsSync(agentSourceRoot)) throw new Error(`Missing project instruction source root: ${agentSourceRoot}`);
 
-        files.push({
-            filepath,
-            relativePath: normalizeProjectPathForGitignore(path.relative(rootDir, filepath)),
-        });
-    }
+    const lines = [
+        managedInstructionSectionHeader,
+        managedInstructionSectionStart,
+        '',
+        managedInstructionSectionIntro,
+        '',
+        '## Agent Routing Contract',
+        '',
+        'Proteum CLI and MCP outputs are optimized for agents. Do not load the whole instruction corpus up front.',
+        '',
+        'Detailed Proteum contracts are intentionally split into the files listed in the routing table below. They are not deleted; load only the file that matches the current task, or use MCP `workflow_start` / `instructions_resolve { projectId }` to get the routed set.',
+        '',
+        '1. When a Proteum MCP client is available, call MCP `workflow_start` first. Pass `cwd` when `projectId` is not known, or pass the stable `projectId` from `projects_list` when it is known.',
+        '2. Use the `projectId` returned by live `workflow_start` for every follow-up app-bound MCP tool. If `workflow_start` is ambiguous or returns offline candidates, call MCP `project_resolve { cwd }`, select the intended app root, follow its port-inspected next action when needed, then retry `workflow_start`.',
+        '3. After `projectId` is selected, use MCP `runtime_status`, `orient`, `instructions_resolve`, `explain_summary`, `route_candidates`, `doctor`, `diagnose`, `trace_show`, `perf_request`, and `logs_tail` for read-only runtime, owner, instruction, route, trace, perf, and log reads.',
+        '4. Do not run CLI equivalents after a successful MCP result for the same read. Do not run broad source searches for route/page/controller ownership after `workflow_start`, `orient`, or `explain_summary` already returned the owner.',
+        '5. Treat selected instruction previews returned by MCP as the instruction source for read-only discovery and diagnostics. Read full files only before edits or git writes, when the returned `fullRead`/`fullReadPolicy` requires it, or when the preview is insufficient.',
+        '6. Use `npx proteum runtime status` before starting a dev server only when MCP runtime status is unavailable, so an existing tracked session can be reused and the configured router/HMR ports can be checked without probing page bodies. If it says health is unreachable, do not run `diagnose`, `trace`, or `perf`; stop/repair/start the dev session first.',
+        '7. During `npx proteum dev`, Proteum ensures one managed machine MCP daemon is running and routes app-bound reads to the read-only runtime endpoint at `/__proteum/mcp` instead of spawning equivalent CLI diagnostics.',
+        '8. If machine MCP routing fails, run `npx proteum mcp status` and `npx proteum runtime status`; if no live session exists, use the exact next action from MCP offline routing or runtime status instead of assuming the manifest default port. If the same app already responds on the configured port without live tracking, use or repair that runtime instead of starting another server.',
+        '9. If a live session exists but runtime/MCP is unreachable, stop the listed session file first, then start dev again. Do not start a second dev server in the same worktree or a second managed MCP daemon. Then retry MCP `workflow_start`.',
+        '10. Use MCP `diagnose { projectId, path }` for request-time issues before raw trace, perf, browser, or broad source search; use `npx proteum diagnose <target>` only as fallback or final terminal evidence.',
+        '11. Use `route_candidates`, `explain_summary`, or `npx proteum explain owner <query>` to pick routes. Do not run `npx proteum explain --routes --full` unless compact route/owner tools explicitly cannot answer the raw route-array question.',
+        '12. Use `--full`, `--manifest`, `--events`, or MCP `detail: "full"` only when compact output says the omitted detail is needed.',
+        '',
+        'CLI remains the reproducible surface for `dev`, `build`, `check`, `verify`, migrations, and final command evidence. MCP remains read-only and returns compact `proteum-mcp-v1` JSON.',
+        '',
+        ...(includeMonorepoRegistry ? renderMonorepoAppRegistry({ appRoot, monorepoRoot }) : []),
+        '## 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.',
+        '- For production changes, add or update focused unit tests for touched behavior when applicable, targeting 100% meaningful coverage for changed production paths.',
+        '- Do not run `git restore` or `git reset`.',
+        '- Keep `proteum dev` sessions tracked with explicit session files and do not replace another live session.',
+        '',
+        '## Triggered Instruction Reads',
+        '',
+        'Keep this root file as a router. MCP-selected previews are enough for read-only discovery and diagnostics. Read the referenced full instruction file only before edits or git writes, when `fullRead`/`fullReadPolicy` requires it, or when the preview is insufficient.',
+        '',
+        '- Git lifecycle (`commit`, `and commit`, `stage`, `push`, `PR`, pull request): read Root contract fallback before any git write.',
+        '- Before finishing production code changes: read Root contract fallback, `CODING_STYLE.md`, `tests/AGENTS.md`, and any touched area `AGENTS.md`.',
+        '- Runtime-visible, request-time, router, SSR, browser, or controller behavior: read Root contract fallback and `diagnostics.md` for verification routing.',
+        '- Non-trivial feature, product, business-rule, UX, copy, or docs changes: read `DOCUMENTATION.md` before editing.',
+        '- Implementation edits: read `CODING_STYLE.md` before editing, plus the matching area file from the routing table.',
+        '',
+        '## Routing Table',
+        '',
+        '- Non-trivial coding tasks, feature docs, product intent, acceptance criteria, or docs updates: read `DOCUMENTATION.md`.',
+        '- 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`.',
+        '- Unit tests, integration tests, or test-area work: read `tests/AGENTS.md`.',
+        '- E2E work: read `tests/AGENTS.md`, `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'))}`,
+        `- Documentation fallback: ${normalizeProjectPathForGitignore(path.join(coreRoot, 'agents', 'project', 'DOCUMENTATION.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'))}`,
+        '',
+    ];
+
+    lines.push(managedInstructionSectionEnd, '');
 
-    return files;
+    return lines.join('\n');
 }
 
 function demoteMarkdownHeadings(content: string) {