proteum 2.3.0 → 2.4.2

package/docs/migrate-from-2.1.3.md

@@ -316,7 +316,7 @@ Only bare `proteum build` and bare `proteum dev` runs print a banner. Other CLI
 - `npx proteum explain`
 - `npx proteum doctor`
 - `npx proteum connect`
-- `npx proteum mcp --url http://localhost:<port>` for repeated agent reads against a running dev app
+- `npx proteum mcp` as the managed machine-scope MCP router; `proteum dev` ensures one daemon is running, agents call `workflow_start` first, use offline candidates to choose the correct app root when needed, then pass the returned live `projectId` to repeated reads against a live dev app
 
 CLI output uses compact `proteum-agent-v1` JSON for reproducible command evidence. MCP output uses compact `proteum-mcp-v1` JSON for repeated runtime reads. Use `npx proteum explain --manifest`, `npx proteum diagnose <target> --full`, or `npx proteum trace show <requestId> --events` only when the compact output is insufficient.
 
@@ -328,7 +328,7 @@ Current `proteum dev` supports tracked session management:
 - `npx proteum dev list --json`
 - `npx proteum dev stop --session-file var/run/proteum/dev/app.json`
 
-If your local workflow starts multiple dev servers, this is the current supported model.
+`proteum dev` fails fast when another live tracked session already exists for the same app root. If runtime/MCP is unreachable, stop the listed session file first, then start dev again instead of launching a second server in the same worktree.
 
 ### New diagnostics are available
 
@@ -337,8 +337,7 @@ These are new capabilities, not migration requirements, but they are the fastest
 - `npx proteum connect --strict`
 - `npx proteum explain --connected --controllers`
 - `npx proteum runtime status`
-- `npx proteum mcp`
-- `npx proteum mcp --url http://localhost:<port>`
+- `npx proteum mcp status` plus MCP `workflow_start`, `project_resolve`, or `projects_list`
 - `npx proteum diagnose / --port <port>`
 - `npx proteum perf top --port <port>`
 - `npx proteum trace latest --port <port>`
@@ -379,7 +378,6 @@ Then boot the app and verify the live runtime:
 ```bash
 npx proteum dev --port 3010
 npx proteum runtime status
-npx proteum mcp --url http://localhost:3010
 npx proteum diagnose / --port 3010
 npx proteum trace latest --port 3010
 ```

package/docs/request-tracing.md

@@ -33,12 +33,12 @@ proteum perf memory --since 1h --group-by controller
 
 Default trace output is compact `proteum-agent-v1` JSON with counts, failed calls, error events, hot calls, and hot SQL. Use `--events` or `--full` only when raw event details, payload summaries, or SQL text are needed.
 
-When an MCP client is available, use MCP `trace_latest`, `trace_show`, `perf_top`, and `perf_request` for repeated reads against the same running app. Keep the CLI commands for reproducible terminal evidence and final verification logs.
+When an MCP client is available, call `workflow_start` with `cwd` or a known `projectId`, then use the returned live `projectId` with MCP `trace_latest`, `trace_show`, `perf_top`, and `perf_request` for repeated reads against the same running app. If `workflow_start` returns offline app candidates or unreachable runtime health, start or repair exactly one `proteum dev` server from the intended app root before trace or perf reads. Keep the CLI commands for reproducible terminal evidence and final verification logs.
 
 Before reproducing a bug or starting a new test pass:
 
-- run `proteum runtime status` to reuse a tracked dev session when possible
-- use MCP `runtime_status` for repeated status checks against the same running server
+- run `proteum runtime status` to reuse a tracked dev session when possible and to get an exact Start Dev action when the configured router/HMR ports are occupied
+- use MCP `runtime_status` with the selected `projectId` for repeated status checks against the same running server
 - if a server is already running, inspect `proteum trace requests`, `proteum trace latest`, and compact `proteum diagnose <path>` first so you can capture past errors without dumping raw events
 
 Typical debugging flow:

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "proteum",
 	"description": "LLM-first Opinionated Typescript Framework for web applications.",
-	"version": "2.3.0",
+	"version": "2.4.2",
 	"author": "Gaetan Le Gac (https://github.com/gaetanlegac)",
 	"repository": "git://github.com/gaetanlegac/proteum.git",
 	"license": "MIT",
@@ -12,6 +12,12 @@
 	"keywords": [
 		"framework"
 	],
+	"scripts": {
+		"test": "vitest run",
+		"test:codex-mcp": "PROTEUM_RUN_CODEX_MCP_USAGE_TEST=1 vitest run tests/codex-mcp-usage.test.cjs",
+		"test:integration": "vitest run tests/dev-transpile-watch.test.cjs",
+		"test:unit": "vitest run --exclude tests/dev-transpile-watch.test.cjs"
+	},
 	"bin": {
 		"proteum": "cli/bin.js"
 	},
@@ -104,13 +110,14 @@
 		"@types/fs-extra": "^9.0.12",
 		"@types/markdown-it": "^12.2.3",
 		"@types/mime-types": "^2.1.1",
-		"@types/node": "^16.9.1",
+		"@types/node": "^20.19.40",
 		"@types/nodemailer": "^6.4.4",
 		"@types/pg": "^8.6.1",
 		"@types/pg-escape": "^0.2.1",
 		"@types/prompts": "^2.0.14",
 		"@types/sharp": "^0.31.1",
 		"@types/universal-analytics": "^0.4.5",
-		"schema-dts": "^1.1.2"
+		"schema-dts": "^1.1.2",
+		"vitest": "^4.1.5"
 	}
 }

package/server/app/devDiagnostics.ts

@@ -1,8 +1,19 @@
 import fs from 'fs-extra';
+import mysql from 'mysql2/promise';
 import path from 'path';
+import { performance } from 'perf_hooks';
 
 import type { Application } from './index';
 import type { TDevConsoleLogLevel, TDevConsoleLogsResponse } from '@common/dev/console';
+import {
+    normalizeDatabaseReadLimit,
+    normalizeDatabaseReadTimeoutMs,
+    validateDatabaseReadQuery,
+    type TDatabaseReadQueryInput,
+    type TDatabaseReadQueryResponse,
+    type TDatabaseReadQueryRow,
+    type TDatabaseReadQueryValue,
+} from '@common/dev/database';
 import {
     buildDoctorResponse,
     explainSectionNames,
@@ -30,12 +41,31 @@ import {
 } from '@common/dev/inspection';
 import type { TProteumManifest } from '@common/dev/proteumManifest';
 import type { TRequestTrace } from '@common/dev/requestTrace';
+import { parseMariaDbDatabaseUrl } from '@server/services/prisma/mariadb';
 
 const isExplainSectionName = (value: string): value is TExplainSectionName =>
     explainSectionNames.includes(value as TExplainSectionName);
 const isConsoleLogLevel = (value: string): value is TDevConsoleLogLevel =>
     ['silly', 'log', 'info', 'warn', 'error'].includes(value);
 
+const normalizeDatabaseValue = (value: unknown): TDatabaseReadQueryValue => {
+    if (value === null || value === undefined) return null;
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') return value;
+    if (typeof value === 'bigint') return value.toString();
+    if (value instanceof Date) return value.toISOString();
+    if (Buffer.isBuffer(value)) return `[Buffer ${value.byteLength} bytes]`;
+
+    return JSON.stringify(value);
+};
+
+const normalizeDatabaseRow = (row: unknown): TDatabaseReadQueryRow => {
+    if (!row || typeof row !== 'object' || Array.isArray(row)) return {};
+
+    return Object.fromEntries(
+        Object.entries(row).map(([key, value]) => [key, normalizeDatabaseValue(value)]),
+    ) as TDatabaseReadQueryRow;
+};
+
 export default class DevDiagnosticsRegistry {
     public constructor(private app: Application) {}
 
@@ -88,6 +118,68 @@ export default class DevDiagnosticsRegistry {
         return { logs: this.app.container.Console.listLogs(limit, isConsoleLogLevel(minimumLevel) ? minimumLevel : 'log') };
     }
 
+    public async databaseReadQuery({
+        limit: rawLimit,
+        sql: rawSql,
+        timeoutMs: rawTimeoutMs,
+    }: TDatabaseReadQueryInput): Promise<TDatabaseReadQueryResponse> {
+        const databaseUrl = process.env.DATABASE_URL;
+        if (!databaseUrl) throw new Error('DATABASE_URL is required before running database diagnostics.');
+
+        const { kind, sql } = validateDatabaseReadQuery(rawSql);
+        const limit = normalizeDatabaseReadLimit(rawLimit);
+        const timeoutMs = normalizeDatabaseReadTimeoutMs(rawTimeoutMs);
+        const connectionConfig = parseMariaDbDatabaseUrl(databaseUrl);
+        const connection = await mysql.createConnection({
+            host: connectionConfig.host,
+            port: connectionConfig.port,
+            user: connectionConfig.user,
+            password: connectionConfig.password,
+            database: connectionConfig.database,
+            connectTimeout: connectionConfig.connectTimeout,
+            multipleStatements: false,
+            supportBigNumbers: true,
+            bigNumberStrings: true,
+            dateStrings: true,
+        });
+        const startedAt = performance.now();
+
+        try {
+            await connection.query('START TRANSACTION READ ONLY');
+            const [rows, fields] = await connection.query({ sql, timeout: timeoutMs });
+            await connection.rollback();
+
+            const rowList = Array.isArray(rows) ? rows : [];
+            const normalizedRows = rowList.map(normalizeDatabaseRow);
+            const elapsedMs = Math.max(0, Math.round(performance.now() - startedAt));
+
+            return {
+                columns: Array.isArray(fields)
+                    ? fields.map((field) => ({
+                          name: field.name,
+                          table: field.table || undefined,
+                          type: field.type,
+                      }))
+                    : [],
+                elapsedMs,
+                kind,
+                limit,
+                limited: normalizedRows.length > limit,
+                rowCount: normalizedRows.length,
+                rows: normalizedRows.slice(0, limit),
+                sql,
+            };
+        } catch (error) {
+            try {
+                await connection.rollback();
+            } catch (_rollbackError) {}
+
+            throw error;
+        } finally {
+            await connection.end();
+        }
+    }
+
     private resolveRequestTrace({ path, requestId }: { path?: string; requestId?: string }): TRequestTrace | undefined {
         if (requestId) return this.app.container.Trace.getRequest(requestId);
         if (!path) return this.app.container.Trace.getLatestRequest();

package/server/app/devMcp.ts

@@ -2,6 +2,7 @@ import { buildContractsDoctorResponse } from '@common/dev/contractsDoctor';
 import { buildDoctorResponse } from '@common/dev/diagnostics';
 import { buildOrientationResponse, explainOwner } from '@common/dev/inspection';
 import {
+    compactDatabaseReadQueryResponse,
     buildRuntimeStatusPayload,
     compactDiagnoseResponse,
     compactDoctorResponse,
@@ -10,7 +11,9 @@ import {
     compactOrientationResponse,
     compactPerfRequestResponse,
     compactPerfTopResponse,
+    compactRouteCandidatesResponse,
     compactTraceResponse,
+    compactWorkflowStartResponse,
     resolveInstructionRouting,
 } from '@common/dev/mcpPayloads';
 import type { TProteumMcpProvider } from '@common/dev/mcpServer';
@@ -64,6 +67,42 @@ export const createRuntimeProteumMcpProvider = ({
                 },
             });
         },
+        async workflowStart({ file, query, route, task }) {
+            const manifest = readManifest();
+            const doctor = buildDoctorResponse(manifest);
+            const contracts = buildContractsDoctorResponse(manifest);
+            const ownerQuery = [route, file, query]
+                .map((value) => value?.trim())
+                .find((value): value is string => Boolean(value));
+
+            return compactWorkflowStartResponse({
+                contracts,
+                doctor,
+                file,
+                health: {
+                    reachable: true,
+                    doctor: doctor.summary,
+                    contracts: contracts.summary,
+                },
+                manifest,
+                owner: ownerQuery ? explainOwner(manifest, ownerQuery) : undefined,
+                query,
+                route,
+                runtime: {
+                    publicUrl,
+                    routerPort,
+                    source: 'proteum-dev-runtime',
+                    mcpUrl: `${publicUrl}/__proteum/mcp`,
+                    traceEnabled: app.container.Trace.isDevTraceEnabled(),
+                    profilerEnabled: app.container.Trace.isProfilingEnabled(),
+                    connectedProjects: Object.entries(app.connectedProjects || {}).map(([namespace, project]) => ({
+                        namespace,
+                        urlInternal: (project as { urlInternal?: string }).urlInternal,
+                    })),
+                },
+                task,
+            });
+        },
         async orient({ query }) {
             return compactOrientationResponse(buildOrientationResponse(readManifest(), query));
         },
@@ -80,6 +119,13 @@ export const createRuntimeProteumMcpProvider = ({
                 query: normalizedQuery,
             });
         },
+        async routeCandidates({ limit, query }) {
+            return compactRouteCandidatesResponse({
+                limit,
+                manifest: readManifest(),
+                query,
+            });
+        },
         async doctor({ contracts = true }) {
             const manifest = readManifest();
 
@@ -144,6 +190,15 @@ export const createRuntimeProteumMcpProvider = ({
                 response: diagnostics().readLogs(limit, level),
             });
         },
+        async dbQuery({ limit, sql, timeoutMs }) {
+            return compactDatabaseReadQueryResponse(
+                await diagnostics().databaseReadQuery({
+                    limit,
+                    sql,
+                    timeoutMs,
+                }),
+            );
+        },
         async readResource(uri) {
             if (uri === 'proteum://runtime/status') return await provider.runtimeStatus({});
             if (uri === 'proteum://instructions/router') return await provider.instructionsResolve({});

package/server/services/prisma/mariadb.ts

@@ -19,7 +19,7 @@ const decodeUrlSegment = (value: string) => {
     return decodeURIComponent(value);
 };
 
-export const createMariaDbAdapter = (databaseUrl: string) => {
+export const parseMariaDbDatabaseUrl = (databaseUrl: string) => {
     const url = new URL(databaseUrl);
 
     if (url.protocol !== 'mysql:' && url.protocol !== 'mariadb:')
@@ -34,7 +34,7 @@ export const createMariaDbAdapter = (databaseUrl: string) => {
     const connectTimeoutSeconds = parseInteger(url.searchParams.get('connect_timeout'));
     const idleTimeoutSeconds = parseInteger(url.searchParams.get('max_idle_connection_lifetime'));
 
-    return new PrismaMariaDb({
+    return {
         host: url.hostname,
         port: parseInteger(url.port) ?? defaultPort,
         user: decodeUrlSegment(url.username),
@@ -43,5 +43,9 @@ export const createMariaDbAdapter = (databaseUrl: string) => {
         connectTimeout: connectTimeoutSeconds ? connectTimeoutSeconds * 1_000 : defaultConnectTimeout,
         idleTimeout: idleTimeoutSeconds ?? defaultIdleTimeout,
         ...(connectionLimit !== undefined ? { connectionLimit } : {}),
-    });
+    };
+};
+
+export const createMariaDbAdapter = (databaseUrl: string) => {
+    return new PrismaMariaDb(parseMariaDbDatabaseUrl(databaseUrl));
 };

package/server/services/router/http/index.ts

@@ -606,6 +606,31 @@ export default class HttpServer<TRouter extends TServerRouter = TServerRouter> {
             }
         });
 
+        routes.post('/__proteum/db/query', async (req, res) => {
+            const sql = typeof req.body?.sql === 'string' ? req.body.sql : '';
+            const rawLimit = Number(req.body?.limit);
+            const rawTimeoutMs = Number(req.body?.timeoutMs);
+
+            try {
+                res.json(
+                    await this.app.getDevDiagnostics().databaseReadQuery({
+                        sql,
+                        limit: Number.isFinite(rawLimit) ? rawLimit : undefined,
+                        timeoutMs: Number.isFinite(rawTimeoutMs) ? rawTimeoutMs : undefined,
+                    }),
+                );
+            } catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                const isUsageError =
+                    message.includes('SQL') ||
+                    message.includes('allowed') ||
+                    message.includes('not allowed') ||
+                    message.includes('DATABASE_URL');
+
+                res.status(isUsageError ? 400 : 500).json({ error: message });
+            }
+        });
+
         routes.get('/__proteum/diagnose', (req, res) => {
             const readString = (value: unknown) => (Array.isArray(value) ? value[0] : value);
             const readNumber = (value: unknown, fallback: number) => {

package/server/services/router/request/ip.test.cjs

@@ -1,5 +1,4 @@
 const assert = require('node:assert/strict');
-const test = require('node:test');
 
 const { resolveRequestIp } = require('./ip.ts');
 

package/tests/agents-utils.test.cjs

@@ -2,7 +2,6 @@ const assert = require('node:assert/strict');
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
-const test = require('node:test');
 
 const coreRoot = path.resolve(__dirname, '..');
 process.env.TS_NODE_PROJECT = path.join(coreRoot, 'cli', 'tsconfig.json');
@@ -24,12 +23,14 @@ const createCoreFixture = () => {
 
     writeFile(path.join(agentsRoot, 'AGENTS.md'), '# Root Contract\n\n- Root rule\n');
     writeFile(path.join(agentsRoot, 'CODING_STYLE.md'), '# Coding Style\n\n- Style rule\n');
+    writeFile(path.join(agentsRoot, 'DOCUMENTATION.md'), '# Documentation\n\n- Documentation rule\n');
     writeFile(path.join(agentsRoot, 'diagnostics.md'), '# Diagnostics\n\n- Diagnostics rule\n');
     writeFile(path.join(agentsRoot, 'optimizations.md'), '# Optimizations\n\n- Optimization rule\n');
     writeFile(path.join(agentsRoot, 'client', 'AGENTS.md'), '# Client Rules\n\n- Client rule\n');
     writeFile(path.join(agentsRoot, 'client', 'pages', 'AGENTS.md'), '# Page Rules\n\n- Page rule\n');
     writeFile(path.join(agentsRoot, 'server', 'routes', 'AGENTS.md'), '# Route Rules\n\n- Route rule\n');
     writeFile(path.join(agentsRoot, 'server', 'services', 'AGENTS.md'), '# Service Rules\n\n- Service rule\n');
+    writeFile(path.join(agentsRoot, 'tests', 'AGENTS.md'), '# Test Rules\n\n- Test rule\n');
     writeFile(path.join(agentsRoot, 'tests', 'e2e', 'AGENTS.md'), '# E2E Rules\n\n- E2E rule\n');
     writeFile(
         path.join(agentsRoot, 'tests', 'e2e', 'REAL_WORLD_JOURNEY_TESTS.md'),
@@ -53,6 +54,7 @@ const createAppFixture = () => {
             '# Proteum-managed instruction files',
             '/AGENTS.md',
             '/CODING_STYLE.md',
+            '/DOCUMENTATION.md',
             '# End Proteum-managed instruction files',
             '/.proteum',
             '',
@@ -62,23 +64,61 @@ const createAppFixture = () => {
     return appRoot;
 };
 
+test('project instruction sources require unit tests for applicable production changes', () => {
+    const projectAgentsRoot = path.join(coreRoot, 'agents', 'project');
+
+    assert.match(
+        fs.readFileSync(path.join(projectAgentsRoot, 'AGENTS.md'), 'utf8'),
+        /production changes must always add or update focused unit tests/,
+    );
+    assert.match(
+        fs.readFileSync(path.join(projectAgentsRoot, 'root', 'AGENTS.md'), 'utf8'),
+        /always add or update focused unit tests/,
+    );
+    assert.match(
+        fs.readFileSync(path.join(projectAgentsRoot, 'tests', 'AGENTS.md'), 'utf8'),
+        /For every production change, add or update focused unit tests/,
+    );
+});
+
 test('standalone configure creates tracked instruction files with routing contract and split docs', () => {
     const coreRoot = createCoreFixture();
     const appRoot = createAppFixture();
     const result = configureProjectAgentInstructions({ appRoot, coreRoot });
     const agentsContent = fs.readFileSync(path.join(appRoot, 'AGENTS.md'), 'utf8');
     const codingStyleContent = fs.readFileSync(path.join(appRoot, 'CODING_STYLE.md'), 'utf8');
+    const documentationContent = fs.readFileSync(path.join(appRoot, 'DOCUMENTATION.md'), 'utf8');
     const gitignoreContent = fs.readFileSync(path.join(appRoot, '.gitignore'), 'utf8');
 
     assert.equal(result.blocked.length, 0);
     assert.match(agentsContent, /^# Proteum Instructions/m);
     assert.match(agentsContent, /<!-- proteum-instructions:start -->/);
     assert.match(agentsContent, /## Agent Routing Contract/);
-    assert.match(agentsContent, /npx proteum orient <query>/);
+    assert.match(agentsContent, /npx proteum runtime status/);
+    assert.match(agentsContent, /MCP `workflow_start`/);
+    assert.match(agentsContent, /project_resolve \{ cwd \}/);
+    assert.match(agentsContent, /instructions_resolve \{ projectId \}/);
+    assert.match(agentsContent, /Do not run CLI equivalents after a successful MCP result/);
+    assert.match(agentsContent, /Read full files only before edits or git writes/);
+    assert.match(agentsContent, /explain_summary/);
+    assert.match(agentsContent, /\/__proteum\/mcp/);
+    assert.match(agentsContent, /proteum-mcp-v1/);
+    assert.match(agentsContent, /## Triggered Instruction Reads/);
+    assert.match(agentsContent, /Git lifecycle/);
+    assert.match(agentsContent, /read Root contract fallback before any git write/);
+    assert.match(agentsContent, /add or update focused unit tests/);
+    assert.match(agentsContent, /read Root contract fallback, `CODING_STYLE\.md`, `tests\/AGENTS\.md`/);
+    assert.match(agentsContent, /MCP-selected previews are enough/);
+    assert.doesNotMatch(agentsContent, /Conventional Commits/);
+    assert.match(agentsContent, /They are not deleted/);
     assert.doesNotMatch(agentsContent, /## Source: CODING_STYLE\.md/);
     assert.match(codingStyleContent, /## Source: CODING_STYLE\.md/);
     assert.match(codingStyleContent, /## Coding Style/);
     assert.doesNotMatch(codingStyleContent, /## Source: client\/AGENTS\.md/);
+    assert.match(documentationContent, /## Source: DOCUMENTATION\.md/);
+    assert.match(documentationContent, /## Documentation/);
+    assert.equal(fs.existsSync(path.join(appRoot, 'tests', 'AGENTS.md')), true);
+    assert.match(fs.readFileSync(path.join(appRoot, 'tests', 'AGENTS.md'), 'utf8'), /Test rule/);
     assert.equal(fs.existsSync(path.join(appRoot, 'tests', 'e2e', 'AGENTS.md')), true);
     assert.equal(fs.existsSync(path.join(appRoot, 'tests', 'e2e', 'REAL_WORLD_JOURNEY_TESTS.md')), true);
     assert.match(fs.readFileSync(path.join(appRoot, 'tests', 'e2e', 'REAL_WORLD_JOURNEY_TESTS.md'), 'utf8'), /Journey rule/);
@@ -86,6 +126,7 @@ test('standalone configure creates tracked instruction files with routing contra
     assert.doesNotMatch(agentsContent, /Before reading or applying instructions from this file/);
     assert.doesNotMatch(gitignoreContent, /Proteum-managed instruction files/);
     assert.doesNotMatch(gitignoreContent, /^\/AGENTS\.md$/m);
+    assert.doesNotMatch(gitignoreContent, /^\/DOCUMENTATION\.md$/m);
 });
 
 test('configure preserves project content outside the managed section', () => {
@@ -176,6 +217,10 @@ test('monorepo configure writes root and app instruction files', () => {
 
     fs.mkdirSync(path.join(monorepoRoot, '.git'));
     fs.mkdirSync(path.join(appRoot, 'client'), { recursive: true });
+    fs.mkdirSync(path.join(appRoot, 'server'), { recursive: true });
+    writeFile(path.join(appRoot, 'package.json'), '{"name":"product"}\n');
+    writeFile(path.join(appRoot, 'identity.config.ts'), 'export default {};\n');
+    writeFile(path.join(appRoot, 'proteum.config.ts'), 'export default {};\n');
 
     configureProjectAgentInstructions({ appRoot, coreRoot });
 
@@ -184,16 +229,26 @@ test('monorepo configure writes root and app instruction files', () => {
     assert.equal(result.mode, 'monorepo');
     assert.equal(resolveProjectAgentMonorepoRoot(appRoot), fs.realpathSync(monorepoRoot));
     assert.match(fs.readFileSync(path.join(monorepoRoot, 'AGENTS.md'), 'utf8'), /## Agent Routing Contract/);
+    assert.match(fs.readFileSync(path.join(monorepoRoot, 'AGENTS.md'), 'utf8'), /## Known Proteum Apps/);
+    assert.match(fs.readFileSync(path.join(monorepoRoot, 'AGENTS.md'), 'utf8'), /apps\/product/);
+    assert.match(fs.readFileSync(path.join(monorepoRoot, 'AGENTS.md'), 'utf8'), /Do not start `npx proteum dev` from this root/);
     assert.match(fs.readFileSync(path.join(monorepoRoot, 'CODING_STYLE.md'), 'utf8'), /## Source: CODING_STYLE\.md/);
+    assert.match(fs.readFileSync(path.join(monorepoRoot, 'DOCUMENTATION.md'), 'utf8'), /## Source: DOCUMENTATION\.md/);
     assert.match(fs.readFileSync(path.join(monorepoRoot, 'diagnostics.md'), 'utf8'), /## Source: diagnostics\.md/);
     assert.match(fs.readFileSync(path.join(monorepoRoot, 'optimizations.md'), 'utf8'), /## Source: optimizations\.md/);
+    assert.match(fs.readFileSync(path.join(monorepoRoot, 'tests', 'AGENTS.md'), 'utf8'), /## Source: tests\/AGENTS\.md/);
     assert.match(fs.readFileSync(path.join(monorepoRoot, 'tests', 'e2e', 'AGENTS.md'), 'utf8'), /## Source: tests\/e2e\/AGENTS\.md/);
     assert.match(fs.readFileSync(path.join(monorepoRoot, 'tests', 'e2e', 'REAL_WORLD_JOURNEY_TESTS.md'), 'utf8'), /## Source: tests\/e2e\/REAL_WORLD_JOURNEY_TESTS\.md/);
     assert.doesNotMatch(fs.readFileSync(path.join(monorepoRoot, 'tests', 'e2e', 'REAL_WORLD_JOURNEY_TESTS.md'), 'utf8'), /## Source: CODING_STYLE\.md/);
+    assert.equal(fs.existsSync(path.join(appRoot, 'tests', 'AGENTS.md')), false);
     assert.equal(fs.existsSync(path.join(appRoot, 'tests', 'e2e', 'AGENTS.md')), false);
-    assert.match(fs.readFileSync(path.join(appRoot, 'AGENTS.md'), 'utf8'), /## Agent Routing Contract/);
+    const appAgentsContent = fs.readFileSync(path.join(appRoot, 'AGENTS.md'), 'utf8');
+    assert.match(appAgentsContent, /## Agent Routing Contract/);
+    assert.doesNotMatch(appAgentsContent, /## Known Proteum Apps/);
+    assert.doesNotMatch(appAgentsContent, /Do not start `npx proteum dev` from this root/);
     assert.match(fs.readFileSync(path.join(appRoot, 'client', 'AGENTS.md'), 'utf8'), /## Source: client\/AGENTS\.md/);
     assert.equal(fs.existsSync(path.join(appRoot, 'CODING_STYLE.md')), false);
+    assert.equal(fs.existsSync(path.join(appRoot, 'DOCUMENTATION.md')), false);
     assert.equal(fs.existsSync(path.join(appRoot, 'diagnostics.md')), false);
     assert.equal(fs.existsSync(path.join(appRoot, 'optimizations.md')), false);
     assert.equal(result.removed.some((entry) => entry.endsWith('/apps/product/CODING_STYLE.md')), true);