proteum 2.4.2 → 2.4.4

package/AGENTS.md

@@ -65,7 +65,7 @@ npx prisma migrate dev --config ./prisma.config.ts --name <migration name>
 - Keep the developer-facing contract synchronized when framework work changes CLI commands, profiler capabilities, or the `proteum dev` banner. Update the live surfaces together in the same pass: CLI command/help definitions, profiler panels and dev-only endpoints, banner text/examples, and the most relevant agent docs that describe them, especially `AGENTS.md`, `agents/project/AGENTS.md`, `agents/project/root/AGENTS.md`, `agents/project/app-root/AGENTS.md`, `agents/project/diagnostics.md`, and any narrower `agents/project/**/AGENTS.md` file that mentions the changed workflow.
 - Proteum MCP contract: `proteum mcp` is the machine-scope router agents register once, and `proteum dev` exposes each app runtime at `/__proteum/mcp`. `proteum dev` ensures one managed machine MCP daemon is running; do not start a second managed daemon. Agents should start with MCP `workflow_start` using `cwd` or a known `projectId`; ambiguous routing or offline app candidates use `project_resolve { cwd }`, and follow-up live app tools require the returned `projectId`. Dev-hosted app tools are already rooted to their own runtime. Keep MCP tools/resources compact, typed, capped, paginated for full trace detail, and read-only unless a future task explicitly expands the mutation contract. The database diagnostic exception is still read-only: MCP `db_query` and CLI `proteum db query` allow one capped `SELECT`, `SHOW`, or `EXPLAIN` statement only and return rows plus elapsed milliseconds. MCP payloads are compact single-line `proteum-mcp-v1` JSON, not pretty-printed human output. Do not implement MCP tools as thin CLI process wrappers when the data is available through manifest readers, tracked sessions, or dev runtime registries.
 - Keep the same-system trace contract explicit when request instrumentation changes: `TRACE_*` controls the retained dev trace store plus the trace/perf CLI, dev-only HTTP endpoints, and bottom profiler, while `ENABLE_PROFILER` enables the reduced request-local `request.profiling` snapshot and `request.finished` hook payload without retaining finished requests globally unless dev trace is also enabled.
-- Current CLI banner contract: only the bare `proteum build` and bare `proteum dev` commands print the welcome banner and include the active Proteum installation method. Any extra argument or option skips the banner. Only `proteum dev` clears the interactive terminal before rendering, exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys in its session UI, and reports connected app names plus successful connected `/ping` checks in the ready banner. Every `proteum dev` start ensures tracked instruction files contain the current managed `# Proteum Instructions` section before the dev loop begins.
+- Current CLI banner contract: only the bare `proteum build` and bare `proteum dev` commands print the welcome banner and include the active Proteum installation method. Any extra argument or option skips the welcome banner. Terminal `proteum mcp` may print a compact central MCP ready banner when it starts or reuses the managed daemon. Only `proteum dev` clears the interactive terminal before rendering, exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys in its session UI, and reports connected app names plus successful connected `/ping` checks in the ready banner. Every `proteum dev` start ensures tracked instruction files contain the current managed `# Proteum Instructions` section before the dev loop begins.
 - Keep core changes aligned with the explicit controller/page architecture in `agents/project/root/AGENTS.md` and its standalone composition in `agents/project/AGENTS.md`.
 - Prefer removing framework magic when the same result can be expressed with explicit contracts, generated code, or typed context.
 - Apply the pruning rules from `agents/project/optimizations.md`, especially for webpack plugins, Babel plugins, aliases, helpers, runtime services, and npm packages that are not meaningfully used by both apps.

package/agents/project/AGENTS.md

@@ -15,6 +15,12 @@ Managed compact root routers must use trigger -> canonical instruction file refe
 
 ## Fast Triggers
 
+- If `cwd` is inside `/.codex/worktrees/`, run Worktree Preflight before implementation:
+  - Copy `.env` from the main worktree when missing.
+  - Run `npx proteum refresh`.
+  - Run `npm i` when dependencies are missing or stale.
+  - Run `npx proteum runtime status`.
+  - For runtime-visible work, start or reuse one tracked `npx proteum dev` session using the Task Lifecycle launch workflow.
 - If you are working in a newly created Proteum worktree, before following the rest of these instructions:
   - Copy `.env` from the main worktree.
   - Run `npx proteum refresh`.
@@ -24,7 +30,7 @@ Managed compact root routers must use trigger -> canonical instruction file refe
 - If the user pastes raw errors without asking for a fix, do not implement changes yet. First run the task-safe local reproduction path: identify the likely app, route, command, or request from the error, boot or reuse the relevant dev server with the elevated-permissions workflow in `Task Lifecycle`, reproduce the failing surface locally, and inspect server output, browser console output, diagnostics, traces, or the smallest relevant command result. If the error does not identify enough context to reproduce, say what is missing and use the available local evidence before guessing. Then list likely causes and, for each one, give probability, why, and how to fix it. After this, every time you implement a fix:
     - test, re-run analysis and give a comparison table of before and after
     - re-print the complete list of suggested fixes, but strike the ones we already implemented or not necessary anymore
-- If the user asks to implement a feature, first inspect the relevant existing surface and state any implementation problem, pain point, attention point, or question you see. If a concern is blocking, or it can materially change product behavior, API shape, architecture, data model, cost, privacy, security, or UX, ask before editing; otherwise state the assumption and continue implementing.
+- If the user asks to implement a feature, first inspect the relevant existing surface and state any implementation problem, pain point, attention point, inconsistency, missing information, or question you see. If anything needs clarification or a decision, pause before editing, ask the user what decision to take, and resume only after the user answers.
 - If the task is ambiguous, generated, connected, or multi-repo, start with MCP `workflow_start` and then MCP `orient { projectId, query }` only if the bootstrap did not return a sufficient owner or next action; use `npx proteum orient <query>` only when MCP is unavailable or terminal evidence is required.
 - Treat Proteum CLI and MCP output as the workflow router. Treat instruction previews returned by MCP `workflow_start` or `instructions_resolve { projectId }` as the allowed instruction scope for read-only discovery and diagnostics. Read full file contents only before edits or git writes, when returned `fullRead`/`fullReadPolicy` requires it, or when the compact preview is insufficient. Do not read broad instruction folders or every managed instruction file up front.
 - When a Proteum MCP client is available, first call MCP `workflow_start` with `cwd` or a known `projectId`. If it is ambiguous or returns offline app candidates, call `project_resolve { cwd }`, select the intended app root, start exactly one dev server from that app root when needed, then retry `workflow_start`. Pass the returned live `projectId` to every follow-up app-bound MCP tool. `npx proteum dev` ensures one managed machine MCP daemon is running; do not start a second managed daemon. Prefer MCP `runtime_status`, `orient`, `instructions_resolve`, `explain_summary`, `route_candidates`, `doctor`, `diagnose`, `trace_show`, `perf_request`, `logs_tail`, and `db_query` for read-only runtime/status/orientation/owner/route/trace/perf/log/database reads. 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 MCP returns the owner. Use CLI commands when you need reproducible terminal validation, dev/build/check workflows, fallback repair, or output to share with a human.
@@ -56,18 +62,20 @@ Managed compact root routers must use trigger -> canonical instruction file refe
 
 ### Before Editing
 
+- Before editing in a `.codex/worktrees` worktree, complete Worktree Preflight from Fast Triggers.
 - Before changing any file, load root-level `CODING_STYLE.md` and any narrower area `AGENTS.md` that applies to the touched files. Do not spend response space explicitly acknowledging those reads unless the user asks.
 
 ### During Implementation
 
 - After running `npx proteum create ...`, adapt the generated code to the real feature instead of leaving placeholder logic in place.
+- If any inconsistency, ambiguity, conflicting source, missing information, or implementation detail needing clarification appears while coding, stop editing immediately, ask the user what decision to take, and resume only after the user answers. Do not silently choose a default or keep implementing under a guessed assumption.
 - When starting a long-lived dev server for an agent task, always request elevated permissions and run `npx proteum dev` outside the sandbox. Use an explicit task/thread-scoped session file such as `var/run/proteum/dev/agents/<task>.json`, inspect `npx proteum runtime status` first, then use its exact Start Dev next action so occupied router/HMR ports are avoided. Do not `curl` normal page routes to identify a port owner; use Proteum runtime status or dev-only `/__proteum/*` endpoints. After the server is ready, print the live server URL as a clickable Markdown link.
 - Use `--replace-existing` only when restarting the exact session file started by the current thread/task. Never replace another live session that belongs to a user, another thread, or an unknown owner.
 - Do not start a second `npx proteum dev` server in the same worktree, and do not start a second managed MCP daemon. If machine MCP routing fails, run `npx proteum mcp status` and `npx proteum runtime status` from the intended app root; if no live session exists, use the exact MCP offline or runtime-status next action 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. If a live session exists but runtime/MCP is unreachable, stop the listed session file first, then start dev again. Do not run diagnose, trace, or perf reads while runtime health is unreachable. Then retry MCP `workflow_start` and use the returned `projectId`.
 - If the current app depends on local `file:` connected projects, boot every connected producer app too, each with its own task-scoped session file and free port, and run every one of those `proteum dev` processes with elevated permissions outside the sandbox before starting or verifying the consumer app.
 - During `npx proteum dev`, the app exposes the read-only Proteum MCP runtime endpoint at `/__proteum/mcp`; use it for repeated agent reads instead of spawning equivalent diagnostics commands. For route/page/controller ownership, prefer MCP `workflow_start`, `route_candidates { projectId, query }`, or `explain_summary { projectId, query }` over broad `npx proteum explain --routes --controllers --full` dumps.
 - For browser validation, use the browser MCP against the running app. Keep Playwright inside `npx proteum e2e --port <port>` for targeted/full end-to-end suites. Bootstrap protected browser MCP state with `npx proteum session`; bootstrap protected E2E runs with `npx proteum e2e --session-email <email> --session-role <role>`.
-- Current CLI banner contract: only the bare `proteum build` and bare `proteum dev` commands print the welcome banner and include the active Proteum installation method. Any extra argument or option skips the banner. Only `proteum dev` clears the interactive terminal before rendering, exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys in its session UI, and reports connected app names plus successful connected `/ping` checks in the ready banner. Every `proteum dev` start ensures tracked instruction files contain the current managed `# Proteum Instructions` section before the dev loop begins.
+- Current CLI banner contract: only the bare `proteum build` and bare `proteum dev` commands print the welcome banner and include the active Proteum installation method. Any extra argument or option skips the welcome banner. Terminal `proteum mcp` may print a compact central MCP ready banner when it starts or reuses the managed daemon. Only `proteum dev` clears the interactive terminal before rendering, exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys in its session UI, and reports connected app names plus successful connected `/ping` checks in the ready banner. Every `proteum dev` start ensures tracked instruction files contain the current managed `# Proteum Instructions` section before the dev loop begins.
 
 ### Before Finishing
 
@@ -332,7 +340,7 @@ Agents working in generated Proteum projects must use this delivery workflow for
 4. Proteum check: refresh and validate generated framework contracts after route, page, controller, service, command, or config changes.
 5. Validate unit + E2E: run the relevant unit tests and real-world journey E2E checks before calling the work complete.
 
-Unit test expectation: production changes must always add or update focused unit tests for the touched behavior when applicable. Target 100% meaningful unit coverage for changed production paths. Any excluded generated files, migrations, framework shims, unreachable defensive branches, or changes that cannot reasonably be unit-tested must be documented in the completion note.
+Unit test expectation: production changes must always add or update focused unit tests and maintain 100% whole-project Vitest unit coverage. Before claiming implementation work complete, run `npx vitest run --coverage` from the repository root and make sure global statements, branches, functions, and lines all meet the configured 100% thresholds. MCP endpoint-reference coverage, touched-path-only coverage, and focused test passes are not substitutes for whole-project Vitest coverage. Any excluded generated files, migrations, framework shims, unreachable defensive branches, or changes that cannot reasonably be unit-tested must be documented in the completion note, and agents must not claim the project has full unit coverage when an exception remains.
 
 E2E expectation: real-world journeys must follow the project-local instructions in `tests/e2e/REAL_WORLD_JOURNEY_TESTS.md`. These tests should model complete user workflows, role transitions, permissions, state changes, and cross-view consistency rather than isolated happy paths.
 

package/agents/project/diagnostics.md

@@ -18,7 +18,7 @@ This file is the canonical source of truth for diagnostics, temporary instrument
 
 - For long-lived dev reproductions, always request elevated permissions and run `npx proteum dev` outside the sandbox. Use an explicit task/thread-scoped session file, inspect `npx proteum runtime status` first, then use its exact next action so occupied router/HMR ports and untracked same-app runtimes are handled without page-body probes. After the server is ready, print the live server URL as a clickable Markdown link.
 - Use `--replace-existing` only when restarting the exact session file started by the current thread/task. Never replace another live session that belongs to a user, another thread, or an unknown owner.
-- Only the bare `npx proteum build` and bare `npx proteum dev` commands print the welcome banner and active Proteum installation method. Any extra argument or option skips the banner. Only `npx proteum dev` clears the interactive terminal before rendering and reports connected app names plus successful connected `/ping` checks in the ready banner; keep that in mind when capturing or comparing command logs during diagnosis. Every `npx proteum dev` start ensures tracked instruction files contain the current managed `# Proteum Instructions` section before the dev loop begins.
+- Only the bare `npx proteum build` and bare `npx proteum dev` commands print the welcome banner and active Proteum installation method. Any extra argument or option skips the welcome banner. Terminal `npx proteum mcp` may print a compact central MCP ready banner when it starts or reuses the managed daemon. Only `npx proteum dev` clears the interactive terminal before rendering and reports connected app names plus successful connected `/ping` checks in the ready banner; keep that in mind when capturing or comparing command logs during diagnosis. Every `npx proteum dev` start ensures tracked instruction files contain the current managed `# Proteum Instructions` section before the dev loop begins.
 - During `npx proteum dev`, the running app exposes the read-only Proteum MCP transport at `/__proteum/mcp`. Use it for runtime-adjacent agent reads instead of repeatedly spawning equivalent CLI diagnostics.
 - If machine MCP routing fails, run `npx proteum mcp status` and `npx proteum runtime status` from the intended app root. If no live session exists, use the exact MCP offline or runtime-status next action so occupied router/HMR ports are avoided. If the same app already responds on the configured port without live tracking, use or repair that runtime instead of starting another server. Do not `curl` normal page routes to identify which app owns a port; use runtime status or Proteum dev-only endpoints. 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, and do not start a second managed MCP daemon. Do not run diagnose, trace, or perf reads while runtime health is unreachable. Then retry MCP `workflow_start` and use the returned `projectId`.
 - For ownership or repo discovery questions, start with MCP `workflow_start`; use MCP `route_candidates { projectId, query }`, MCP `orient { projectId, query }`, and MCP `explain_summary { projectId, query }` only when the bootstrap owner summary is insufficient. Use `npx proteum orient <query>` or `npx proteum explain owner <query>` only when MCP is unavailable or terminal evidence is required.

package/agents/project/root/AGENTS.md

@@ -15,7 +15,7 @@ Managed compact root routers must use trigger -> canonical instruction file refe
 ## Fast Triggers
 
 - If the user pastes raw errors without asking for a fix, do not implement changes yet. First run the task-safe local reproduction path: identify the likely app, route, command, or request from the error, boot or reuse the relevant dev server with the elevated-permissions workflow in `Task Lifecycle`, reproduce the failing surface locally, and inspect server output, browser console output, diagnostics, traces, or the smallest relevant command result. If the error does not identify enough context to reproduce, say what is missing and use the available local evidence before guessing. Then list likely causes and, for each one, give probability, why, and how to fix it.
-- If the user asks to implement a feature, first inspect the relevant existing surface and state any implementation problem, pain point, attention point, or question you see. If a concern is blocking, or it can materially change product behavior, API shape, architecture, data model, cost, privacy, security, or UX, ask before editing; otherwise state the assumption and continue implementing.
+- If the user asks to implement a feature, first inspect the relevant existing surface and state any implementation problem, pain point, attention point, inconsistency, missing information, or question you see. If anything needs clarification or a decision, pause before editing, ask the user what decision to take, and resume only after the user answers.
 - If the task is ambiguous, generated, connected, or multi-repo, start with MCP `workflow_start` and then MCP `orient { projectId, query }` only if the bootstrap did not return a sufficient owner or next action; use `npx proteum orient <query>` only when MCP is unavailable or terminal evidence is required.
 - Treat Proteum CLI and MCP output as the workflow router. Treat instruction previews returned by MCP `workflow_start` or `instructions_resolve { projectId }` as the allowed instruction scope for read-only discovery and diagnostics. Read full file contents only before edits or git writes, when returned `fullRead`/`fullReadPolicy` requires it, or when the compact preview is insufficient. Do not read broad instruction folders or every managed instruction file up front.
 - When a Proteum MCP client is available, first call MCP `workflow_start` with `cwd` or a known `projectId`. If it is ambiguous or returns offline app candidates, call `project_resolve { cwd }`, select the intended app root, start exactly one dev server from that app root when needed, then retry `workflow_start`. Pass the returned live `projectId` to every follow-up app-bound MCP tool. `npx proteum dev` ensures one managed machine MCP daemon is running; do not start a second managed daemon. Prefer MCP `runtime_status`, `orient`, `instructions_resolve`, `explain_summary`, `route_candidates`, `doctor`, `diagnose`, `trace_show`, `perf_request`, `logs_tail`, and `db_query` for read-only runtime/status/orientation/owner/route/trace/perf/log/database reads. 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 MCP returns the owner. Use CLI commands when you need reproducible terminal validation, dev/build/check workflows, fallback repair, or output to share with a human.
@@ -51,18 +51,19 @@ Managed compact root routers must use trigger -> canonical instruction file refe
 ### During Implementation
 
 - After running `npx proteum create ...`, adapt the generated code to the real feature instead of leaving placeholder logic in place.
+- If any inconsistency, ambiguity, conflicting source, missing information, or implementation detail needing clarification appears while coding, stop editing immediately, ask the user what decision to take, and resume only after the user answers. Do not silently choose a default or keep implementing under a guessed assumption.
 - When starting a long-lived dev server for an agent task, always request elevated permissions and run `npx proteum dev` outside the sandbox. Use an explicit task/thread-scoped session file such as `var/run/proteum/dev/agents/<task>.json`, inspect `npx proteum runtime status` first, then use its exact Start Dev next action so occupied router/HMR ports are avoided. Do not `curl` normal page routes to identify a port owner; use Proteum runtime status or dev-only `/__proteum/*` endpoints. After the server is ready, print the live server URL as a clickable Markdown link.
 - Use `--replace-existing` only when restarting the exact session file started by the current thread/task. Never replace another live session that belongs to a user, another thread, or an unknown owner.
 - Do not start a second `npx proteum dev` server in the same worktree, and do not start a second managed MCP daemon. If machine MCP routing fails, run `npx proteum mcp status` and `npx proteum runtime status` from the intended app root; if no live session exists, use the exact MCP offline or runtime-status next action 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. If a live session exists but runtime/MCP is unreachable, stop the listed session file first, then start dev again. Do not run diagnose, trace, or perf reads while runtime health is unreachable. Then retry MCP `workflow_start` and use the returned `projectId`.
 - If the current app depends on local `file:` connected projects, boot every connected producer app too, each with its own task-scoped session file and free port, and run every one of those `proteum dev` processes with elevated permissions outside the sandbox before starting or verifying the consumer app.
 - During `npx proteum dev`, the app exposes the read-only Proteum MCP runtime endpoint at `/__proteum/mcp`; use it for repeated agent reads instead of spawning equivalent diagnostics commands. For route/page/controller ownership, prefer MCP `workflow_start`, `route_candidates { projectId, query }`, or `explain_summary { projectId, query }` over broad `npx proteum explain --routes --controllers --full` dumps.
 - For browser validation, use the browser MCP against the running app. Keep Playwright inside `npx proteum e2e --port <port>` for targeted/full end-to-end suites. Bootstrap protected browser MCP state with `npx proteum session`; bootstrap protected E2E runs with `npx proteum e2e --session-email <email> --session-role <role>`.
-- Current CLI banner contract: only the bare `proteum build` and bare `proteum dev` commands print the welcome banner and include the active Proteum installation method. Any extra argument or option skips the banner. Only `proteum dev` clears the interactive terminal before rendering, exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys in its session UI, and reports connected app names plus successful connected `/ping` checks in the ready banner. Every `proteum dev` start ensures tracked instruction files contain the current managed `# Proteum Instructions` section before the dev loop begins.
+- Current CLI banner contract: only the bare `proteum build` and bare `proteum dev` commands print the welcome banner and include the active Proteum installation method. Any extra argument or option skips the welcome banner. Terminal `proteum mcp` may print a compact central MCP ready banner when it starts or reuses the managed daemon. Only `proteum dev` clears the interactive terminal before rendering, exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys in its session UI, and reports connected app names plus successful connected `/ping` checks in the ready banner. Every `proteum dev` start ensures tracked instruction files contain the current managed `# Proteum Instructions` section before the dev loop begins.
 
 ### Before Finishing
 
 - Before finishing, re-check touched files against root-level `CODING_STYLE.md` and any narrower area `AGENTS.md` that applied to the edit. Re-check against root-level `optimizations.md` only for touched client-side files. Re-check against root-level `diagnostics.md` only if the task involved an issue, diagnosis, runtime reproduction, or verification failure.
-- For production changes, always add or update focused unit tests for the touched behavior when applicable. Target 100% meaningful unit coverage for changed production paths, and document any generated files, migrations, framework shims, unreachable defensive branches, or changes that cannot reasonably be unit-tested.
+- For production changes, always add or update focused unit tests and maintain 100% whole-project Vitest unit coverage. Before claiming implementation work complete, run `npx vitest run --coverage` from the repository root and make sure global statements, branches, functions, and lines all meet the configured 100% thresholds. MCP endpoint-reference coverage, touched-path-only coverage, and focused test passes are not substitutes for whole-project Vitest coverage. Document any generated files, migrations, framework shims, unreachable defensive branches, or changes that cannot reasonably be unit-tested as explicit exceptions, and do not claim the project has full unit coverage when an exception remains.
 - Run the full project `npx proteum check` before finishing each feature or change. Targeted lint, typecheck, diagnose, request, browser, or E2E runs are still useful while iterating, but they do not replace the final full check. After implementing a new feature or changing existing feature behavior, always update the end-to-end coverage for that behavior and run the full Playwright test suite before finishing. For docs-only, wording-only, type-only, test-only, generated-output cleanup, or clearly local non-runtime refactors, skip Playwright unless the user explicitly asks for it or verification reveals a real issue.
 - Before finishing a task, stop every `proteum dev` session started during the task and confirm cleanup with `npx proteum dev list --json` or an explicit `npx proteum dev stop --session-file <path>`.
 - When you have finished your work, ask the user whether they want a commit message. After providing a commit message or after creating a commit, immediately follow it with this exact prompt and obey it:

package/agents/project/tests/AGENTS.md

@@ -9,7 +9,7 @@ Diagnostics source of truth: root-level `diagnostics.md`.
 
 - Understand the real user flow and the main feature branches before writing tests.
 - Test the current controller/page runtime model, not legacy `@Route` or `api.fetch(...)` behavior.
-- For every production change, add or update focused unit tests when applicable. Target 100% meaningful coverage for changed production paths, and document any generated files, migrations, framework shims, unreachable defensive branches, or changes that cannot reasonably be unit-tested.
+- For every production change, add or update focused unit tests and maintain 100% whole-project Vitest unit coverage. Before claiming implementation work complete, run `npx vitest run --coverage` from the repository root and make sure global statements, branches, functions, and lines all meet the configured 100% thresholds. MCP endpoint-reference coverage, touched-path-only coverage, and focused test passes are not substitutes for whole-project Vitest coverage. Document any generated files, migrations, framework shims, unreachable defensive branches, or changes that cannot reasonably be unit-tested as explicit exceptions, and do not claim the project has full unit coverage when an exception remains.
 - Verify routing, controllers, SSR, and router plugins against a running app when behavior depends on real request handling.
 - After implementing a new feature or changing existing feature behavior, update the end-to-end coverage for that behavior and run the full Playwright suite before finishing. Prefer `npx proteum e2e --port <port>` for Playwright runs so base URLs and auth tokens are passed through Proteum-managed child env instead of shell-leading environment assignments. Use a browser MCP repro against a running app during iteration when it is the fastest trustworthy loop.
 - Exercise real URLs, generated controller calls, or real browser flows instead of re-deriving framework internals in tests.

package/cli/commands/mcp.ts

@@ -6,6 +6,7 @@ import {
     resolveMachineMcpDaemonPort,
     stopMachineMcpDaemonProcess,
 } from '../runtime/mcpDaemon';
+import { renderMcpDaemonBanner } from '../presentation/mcp';
 
 const printJson = (payload: unknown) => {
     process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
@@ -53,11 +54,19 @@ const runDaemon = async () => {
             return;
         }
 
-        console.info(`Proteum machine MCP daemon is already running at ${existing.record.mcpUrl} (pid ${existing.record.pid}).`);
+        console.info(
+            await renderMcpDaemonBanner({
+                mcpUrl: existing.record.mcpUrl,
+                pid: existing.record.pid,
+                state: 'connected',
+            }),
+        );
         return;
     }
 
     const port = resolveMachineMcpDaemonPort(typeof cli.args.port === 'string' ? cli.args.port : undefined);
+    const mcpUrl = `http://127.0.0.1:${port}/mcp`;
+    const healthUrl = `http://127.0.0.1:${port}/health`;
 
     await startProteumMachineMcpRouterHttp({
         port,
@@ -69,12 +78,18 @@ const runDaemon = async () => {
             started: true,
             daemon: {
                 pid: process.pid,
-                mcpUrl: `http://127.0.0.1:${port}/mcp`,
-                healthUrl: `http://127.0.0.1:${port}/health`,
+                mcpUrl,
+                healthUrl,
             },
         });
     } else {
-        console.info(`Proteum machine MCP daemon started at http://127.0.0.1:${port}/mcp.`);
+        console.info(
+            await renderMcpDaemonBanner({
+                mcpUrl,
+                pid: process.pid,
+                state: 'started',
+            }),
+        );
     }
 };
 
@@ -91,9 +106,11 @@ const ensureDaemon = async () => {
 
     if (result.inspection.record) {
         console.info(
-            result.started
-                ? `Proteum machine MCP daemon started at ${result.inspection.record.mcpUrl}.`
-                : `Proteum machine MCP daemon is already running at ${result.inspection.record.mcpUrl}.`,
+            await renderMcpDaemonBanner({
+                mcpUrl: result.inspection.record.mcpUrl,
+                pid: result.inspection.record.pid,
+                state: result.started ? 'started' : 'connected',
+            }),
         );
     }
 };

package/cli/presentation/commands.ts

@@ -459,16 +459,16 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         summary: 'Run one capped read-only database diagnostic query against a running Proteum dev server.',
         usage: 'proteum db [query] <sql> [--limit <rows>] [--timeout <ms>] [--port <port>|--url <baseUrl>] [--full]',
         bestFor:
-            'Inspecting live MySQL or MariaDB state during diagnosis without giving agents a write-capable SQL execution surface.',
+            'Inspecting live MySQL, MariaDB, or PostgreSQL state during diagnosis without giving agents a write-capable SQL execution surface.',
         examples: [
             { description: 'Run a small SELECT diagnostic', command: 'proteum db query "SELECT id, email FROM User LIMIT 5"' },
-            { description: 'Inspect table metadata', command: 'proteum db "SHOW TABLES"' },
+            { description: 'Inspect table metadata', command: 'proteum db "SELECT table_name FROM information_schema.tables LIMIT 20"' },
             { description: 'Explain a query plan', command: 'proteum db query "EXPLAIN SELECT * FROM User WHERE id = 1"' },
         ],
         notes: [
             'Only SELECT, SHOW, and EXPLAIN statements are allowed.',
             'The dev runtime executes the query with the app DATABASE_URL and returns rows, columns, elapsedMs, and cap metadata.',
-            'Multi-statement SQL, EXPLAIN ANALYZE, locking reads, LOAD_FILE, SELECT INTO OUTFILE, sleep, and benchmark functions are rejected.',
+            'Multi-statement SQL, EXPLAIN ANALYZE, locking reads, file-read functions, SELECT INTO OUTFILE, sleep, and benchmark functions are rejected.',
             'Default output is compact `proteum-agent-v1` JSON with capped rows; use `--full` for the raw dev endpoint payload.',
         ],
         status: 'experimental',
@@ -508,6 +508,7 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         ],
         notes: [
             '`proteum dev` ensures one managed machine MCP daemon is running before the app dev loop starts.',
+            'Terminal `proteum mcp` prints a compact central MCP banner with the Streamable HTTP URL for client setup.',
             '`proteum mcp` is a router, not an app dev server. It discovers live `proteum dev` sessions from the machine registry and can resolve offline app candidates from `cwd`.',
             'Agents should call MCP `workflow_start` with `cwd` or a known `projectId`; use `project_resolve { cwd }` when routing is ambiguous or no live dev server exists yet.',
             'When an offline app candidate is returned, start exactly one `proteum dev` from that app root before runtime diagnose, trace, or perf reads.',

package/cli/presentation/help.ts

@@ -135,7 +135,7 @@ export const renderCliOverview = async ({
                     indent: '  ',
                     nextIndent: '  ',
                 }),
-                wrapText('Only the bare `proteum build` and bare `proteum dev` commands print the welcome banner and active Proteum installation method. Any extra argument or option skips the banner. `proteum dev` is the only command that clears the interactive terminal before rendering its session UI.', {
+                wrapText('Only the bare `proteum build` and bare `proteum dev` commands print the welcome banner and active Proteum installation method. Any extra argument or option skips the welcome banner. `proteum mcp` may print a compact central MCP ready banner when it starts or reuses the daemon. `proteum dev` is the only command that clears the interactive terminal before rendering its session UI.', {
                     indent: '  ',
                     nextIndent: '  ',
                 }),

package/cli/presentation/mcp.ts

@@ -0,0 +1,27 @@
+import { CliReact, renderInk } from './ink';
+
+export type TMcpDaemonBannerState = 'started' | 'connected';
+
+export const renderMcpDaemonBanner = async ({
+    mcpUrl,
+    pid,
+    state,
+}: {
+    mcpUrl: string;
+    pid?: number;
+    state: TMcpDaemonBannerState;
+}) =>
+    renderInk(({ Box, Text }) => {
+        const createElement = CliReact.createElement;
+        const summary =
+            state === 'started' ? 'Launched central MCP server.' : 'Connected to central MCP server.';
+        const pidLabel = pid ? ` pid ${pid}` : '';
+
+        return createElement(
+            Box,
+            { borderStyle: 'round', borderColor: 'cyan', paddingX: 2, paddingY: 0, flexDirection: 'column' },
+            createElement(Text, { bold: true, backgroundColor: 'cyan', color: 'black' }, ' CENTRAL MCP READY '),
+            createElement(Text, { bold: true, color: 'cyan' }, `${summary}${pidLabel}`),
+            createElement(Text, { dimColor: true }, `Connect MCP client (HTTP): ${mcpUrl}`),
+        );
+    });

package/cli/utils/agents.ts

@@ -617,11 +617,12 @@ function renderEmbeddedProjectInstructions({ appRoot, coreRoot, includeMonorepoR
         '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.',
+        '8. Terminal `npx proteum mcp` prints a compact central MCP ready banner with the HTTP client URL when it starts or reuses the managed daemon.',
+        '9. 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.',
+        '10. 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`.',
+        '11. 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.',
+        '12. 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.',
+        '13. 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.',
         '',
@@ -650,6 +651,7 @@ function renderEmbeddedProjectInstructions({ appRoot, coreRoot, includeMonorepoR
         '## Routing Table',
         '',
         '- Non-trivial coding tasks, feature docs, product intent, acceptance criteria, or docs updates: read `DOCUMENTATION.md`.',
+        '- GEO/SEO/crawler/structured-data/AI-source changes: read `DOCUMENTATION.md`, `CODING_STYLE.md`, `tests/AGENTS.md`, and update or create a docs page under `docs/` describing the public contract, routes, validation, and operational caveats.',
         '- 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`.',

package/common/dev/database.ts

@@ -199,15 +199,18 @@ const assertAllowedReadQueryShape = (sql: string) => {
         throw new Error('SELECT INTO OUTFILE and SELECT INTO DUMPFILE are not allowed.');
     }
 
-    if (/\bload_file\s*\(/.test(normalized)) {
-        throw new Error('LOAD_FILE is not allowed in database diagnostics.');
+    if (/\b(?:load_file|pg_read_file|pg_read_binary_file|pg_ls_dir)\s*\(/.test(normalized)) {
+        throw new Error('Database file-read functions are not allowed in database diagnostics.');
     }
 
-    if (/\bfor\s+update\b/.test(normalized) || /\block\s+in\s+share\s+mode\b/.test(normalized)) {
+    if (
+        /\bfor\s+(?:update|no\s+key\s+update|share|key\s+share)\b/.test(normalized) ||
+        /\block\s+in\s+share\s+mode\b/.test(normalized)
+    ) {
         throw new Error('Locking read statements are not allowed in database diagnostics.');
     }
 
-    if (/\b(?:sleep|benchmark)\s*\(/.test(normalized)) {
+    if (/\b(?:sleep|benchmark|pg_sleep|pg_sleep_for|pg_sleep_until)\s*\(/.test(normalized)) {
         throw new Error('Sleep and benchmark functions are not allowed in database diagnostics.');
     }
 };

package/docs/agent-routing.md

@@ -66,7 +66,7 @@ Use MCP for repeated reads when a client is available:
 proteum mcp
 ```
 
-The machine router discovers live `proteum dev` sessions and offline Proteum app roots under a cwd. `proteum dev` ensures one managed machine MCP daemon is running; terminal `proteum mcp` starts or reuses that daemon, while MCP clients can use stdio. Agents should call MCP `workflow_start` with `cwd` or a known `projectId`, use `project_resolve { cwd }` when routing is ambiguous or offline, and pass the returned live `projectId` to every follow-up app-bound MCP tool. Offline candidates include port-inspected next actions, so agents should follow those instead of guessing the manifest default port. The router forwards to the selected dev-hosted `/__proteum/mcp` endpoint and strips routing fields before the app sees the call.
+The machine router discovers live `proteum dev` sessions and offline Proteum app roots under a cwd. `proteum dev` ensures one managed machine MCP daemon is running; terminal `proteum mcp` starts or reuses that daemon and prints a compact central MCP banner with the HTTP client URL, while MCP clients can use stdio. Agents should call MCP `workflow_start` with `cwd` or a known `projectId`, use `project_resolve { cwd }` when routing is ambiguous or offline, and pass the returned live `projectId` to every follow-up app-bound MCP tool. Offline candidates include port-inspected next actions, so agents should follow those instead of guessing the manifest default port. The router forwards to the selected dev-hosted `/__proteum/mcp` endpoint and strips routing fields before the app sees the call.
 
 If machine MCP routing returns offline candidates, choose the intended app root and follow that candidate's next action from the app root, not from the monorepo wrapper. If machine MCP routing fails, run `proteum mcp status` and `proteum runtime status` from the intended app root; if no live session exists, use the exact Start Dev next action from runtime status so occupied router/HMR ports are avoided. If the same app already responds on the configured port without live tracking, use or repair that runtime instead of starting another server. Do not `curl` normal page routes to identify which app owns a port; use runtime status or Proteum dev-only endpoints. If a live session exists but runtime/MCP is unreachable, stop the listed session file first, then start dev again. Do not run diagnose, trace, or perf reads while runtime health is unreachable. Do not start a second dev server in the same worktree, and do not start a second managed MCP daemon. Then retry MCP `workflow_start`.
 

package/docs/mcp.md

@@ -15,7 +15,7 @@ Start the router from any directory:
 proteum mcp
 ```
 
-When run from a terminal, `proteum mcp` starts or reuses the managed local daemon at `http://127.0.0.1:3769/mcp`. When an MCP client launches it over pipes, use stdio:
+When run from a terminal, `proteum mcp` starts or reuses the managed local daemon at `http://127.0.0.1:3769/mcp`. The terminal output prints a compact `CENTRAL MCP READY` banner with the one-line client setup instruction, `Connect MCP client (HTTP): <mcp-url>`. When an MCP client launches it over pipes, use stdio:
 
 ```bash
 proteum mcp --stdio
@@ -171,7 +171,7 @@ db_query { projectId, sql, limit? }
 
 After an MCP read succeeds, do not run the equivalent CLI command for the same state, and do not run broad source searches for ownership that MCP already returned. CLI output is for fallback, validation, command evidence, and human-shareable reproductions.
 
-Database diagnostics are intentionally read-only. `db_query` and `proteum db query` accept only one `SELECT`, `SHOW`, or `EXPLAIN` statement, return rows, columns, elapsed milliseconds, and cap metadata, and reject multi-statement SQL, `EXPLAIN ANALYZE`, locking reads, file reads/writes, sleep, and benchmark functions.
+Database diagnostics are intentionally read-only. `db_query` and `proteum db query` support MySQL, MariaDB, PostgreSQL, and PostgreSQL-compatible `DATABASE_URL` protocols. They accept only one `SELECT`, `SHOW`, or `EXPLAIN` statement, return rows, columns, elapsed milliseconds, and cap metadata, and reject multi-statement SQL, `EXPLAIN ANALYZE`, locking reads, file reads/writes, sleep, and benchmark functions.
 
 
 ## Benchmark

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "proteum",
 	"description": "LLM-first Opinionated Typescript Framework for web applications.",
-	"version": "2.4.2",
+	"version": "2.4.4",
 	"author": "Gaetan Le Gac (https://github.com/gaetanlegac)",
 	"repository": "git://github.com/gaetanlegac/proteum.git",
 	"license": "MIT",
@@ -76,6 +76,7 @@
 		"node-cmd": "^5.0.0",
 		"null-loader": "^4.0.1",
 		"path-to-regexp": "^6.2.0",
+		"pg": "^8.21.0",
 		"postcss-loader": "^8.2.0",
 		"preact": "^10.27.1",
 		"preact-render-to-string": "^6.6.1",

package/server/app/container/console/http-client-error-context.test.cjs

@@ -0,0 +1,96 @@
+const assert = require('node:assert/strict');
+const path = require('node:path');
+
+const coreRoot = path.resolve(__dirname, '../../../..');
+process.env.TS_NODE_PROJECT = path.join(coreRoot, 'cli', 'tsconfig.json');
+process.env.TS_NODE_TRANSPILE_ONLY = '1';
+require('ts-node/register/transpile-only');
+
+const moduleAlias = require('module-alias');
+moduleAlias.addAliases({
+    '@client': path.join(coreRoot, 'client'),
+    '@common': path.join(coreRoot, 'common'),
+    '@server': path.join(coreRoot, 'server'),
+});
+
+const { default: Console, getHttpClientErrorContext, normalizeBugReportError } = require('./index.ts');
+
+test('wraps got HTTP errors as anomalies with original error context', () => {
+    const error = new Error('Response code 422 (Unprocessable Entity)');
+    error.name = 'HTTPError';
+    error.code = 'ERR_NON_2XX_3XX_RESPONSE';
+    error.timings = {
+        phases: {
+            total: 321,
+        },
+    };
+    error.request = {
+        options: {
+            method: 'GET',
+            url: 'https://api.example.test/ip/2001:db8::1',
+            headers: {
+                'x-key': 'secret-token',
+            },
+        },
+    };
+    error.response = {
+        statusCode: 422,
+        statusMessage: 'Unprocessable Entity',
+        headers: {
+            'set-cookie': 'session=secret',
+        },
+        body: {
+            message: 'Invalid IP address',
+        },
+    };
+
+    const wrapped = normalizeBugReportError(error);
+
+    assert.equal(wrapped.message, 'HTTP client request failed.');
+    assert.equal(wrapped.originalError, error);
+    assert.deepEqual(wrapped.dataForDebugging, {
+        code: 'ERR_NON_2XX_3XX_RESPONSE',
+        statusCode: 422,
+        statusMessage: 'Unprocessable Entity',
+        method: 'GET',
+        url: 'https://api.example.test/ip/2001:db8::1',
+        timings: {
+            phases: {
+                total: 321,
+            },
+        },
+        request: {
+            options: {
+                method: 'GET',
+                url: 'https://api.example.test/ip/2001:db8::1',
+                headers: {
+                    'x-key': 'secret-token',
+                },
+            },
+        },
+        response: {
+            statusCode: 422,
+            statusMessage: 'Unprocessable Entity',
+            headers: {
+                'set-cookie': 'session=secret',
+            },
+            body: {
+                message: 'Invalid IP address',
+            },
+        },
+        options: null,
+    });
+});
+
+test('ignores normal application errors', () => {
+    assert.equal(getHttpClientErrorContext(new Error('Something else failed')), null);
+});
+
+test('renders circular JSON contexts in bug report HTML', () => {
+    const context = { name: 'request' };
+    context.self = context;
+
+    const html = Console.prototype.jsonToHTML.call({ printHtml: (value) => value }, context);
+
+    assert.match(html, /Circular/);
+});

package/server/app/container/console/index.ts

@@ -7,6 +7,7 @@ import { serialize } from 'v8';
 import { formatWithOptions } from 'util';
 import md5 from 'md5';
 import dayjs from 'dayjs';
+import stringify from 'fast-safe-stringify';
 
 // Npm
 import { Logger, IMeta, ILogObj, ISettings } from 'tslog';
@@ -17,7 +18,7 @@ import Ansi2Html from 'ansi-to-html';
 import type ApplicationContainer from '..';
 import context from '@server/context';
 import type { TDevConsoleLogChannel, TDevConsoleLogEntry, TDevConsoleLogLevel } from '@common/dev/console';
-import type { ServerBug, TCatchedError } from '@common/errors';
+import { Anomaly, type ServerBug, type TCatchedError } from '@common/errors';
 import type { TTraceCallOrigin, TTraceSqlQueryKind } from '@common/dev/requestTrace';
 import type ServerRequest from '@server/services/router/request';
 
@@ -74,6 +75,13 @@ export type TDbQueryLog = ChannelInfos & { date: Date; query: string; time: numb
 export type TLogLevel = keyof typeof logLevels;
 
 export type TJsonLog = { time: Date; level: TLogLevel; args: unknown[]; channel: ChannelInfos };
+type TGotLikeError = Error & {
+    code?: unknown;
+    timings?: unknown;
+    request?: unknown;
+    response?: unknown;
+    options?: unknown;
+};
 
 /*----------------------------------
 - CONST
@@ -111,6 +119,57 @@ var ansi2Html = new Ansi2Html({
 
 type TWrappedConsole = typeof console & { _wrapped?: boolean };
 
+const isRecord = (value: unknown): value is Record<string, unknown> => {
+    return typeof value === 'object' && value !== null;
+};
+
+const firstString = (...values: Array<unknown>): string | null => {
+    for (const value of values) {
+        if (typeof value === 'string' && value.trim()) return value;
+        if (value instanceof URL) return value.toString();
+    }
+
+    return null;
+};
+
+export const getHttpClientErrorContext = (error: Error): object | null => {
+    const gotError = error as TGotLikeError;
+    const errorRecord = gotError as unknown as Record<string, unknown>;
+    const code = typeof gotError.code === 'string' ? gotError.code : null;
+    const response = isRecord(gotError.response) ? gotError.response : null;
+    const request = isRecord(gotError.request) ? gotError.request : null;
+    const requestOptions = request && isRecord(request.options) ? request.options : null;
+    const fallbackOptions = isRecord(gotError.options) ? gotError.options : null;
+    const options = requestOptions || fallbackOptions;
+
+    if (error.name !== 'HTTPError' && code !== 'ERR_NON_2XX_3XX_RESPONSE' && !response) return null;
+
+    return {
+        code,
+        statusCode: response && typeof response.statusCode === 'number' ? response.statusCode : null,
+        statusMessage: response && typeof response.statusMessage === 'string' ? response.statusMessage : null,
+        method: options && typeof options.method === 'string' ? options.method : null,
+        url: firstString(
+            response ? response.requestUrl : null,
+            response ? response.url : null,
+            request ? request.requestUrl : null,
+            options ? options.url : null,
+            errorRecord.url,
+        ),
+        timings: gotError.timings || null,
+        request: request || null,
+        response: response || null,
+        options: fallbackOptions,
+    };
+};
+
+export const normalizeBugReportError = (error: TCatchedError): TCatchedError => {
+    const httpClientErrorContext = getHttpClientErrorContext(error);
+    if (!httpClientErrorContext) return error;
+
+    return new Anomaly('HTTP client request failed.', httpClientErrorContext, error);
+};
+
 /*----------------------------------
 - LOGGER
 ----------------------------------*/
@@ -307,7 +366,7 @@ export default class Console {
         // On envoi l'email avant l'insertion dans bla bdd
         // Car cette denrière a plus de chances de provoquer une erreur
         //const logs = this.logs.filter(e => e.channel.channelId === channelId).slice(-100);
-        const inspection = this.getDetailledError(error);
+        const inspection = this.getDetailledError(normalizeBugReportError(error));
 
         // Genertae unique error hash
         const hash = md5(inspection.stacktraces[0]);
@@ -480,7 +539,7 @@ Logs: ${
     public jsonToHTML(json: unknown): string {
         if (!json) return 'No data';
 
-        const coloredJson = highlight(JSON.stringify(json, null, 4), { language: 'json', ignoreIllegals: true });
+        const coloredJson = highlight(stringify(json, null, 4), { language: 'json', ignoreIllegals: true });
 
         const html = ansi2Html.toHtml(coloredJson);
 

package/server/app/devDatabase.ts

@@ -0,0 +1,183 @@
+import mysql from 'mysql2/promise';
+import { Client as PostgresClient } from 'pg';
+import { performance } from 'perf_hooks';
+
+import type {
+    TDatabaseReadQueryColumn,
+    TDatabaseReadQueryResponse,
+    TDatabaseReadQueryRow,
+    TDatabaseReadQueryValue,
+} from '@common/dev/database';
+import { parseMariaDbDatabaseUrl } from '@server/services/prisma/mariadb';
+
+type TDatabaseProtocol = 'mariadb' | 'postgresql';
+
+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 const databaseProtocolFromUrl = (databaseUrl: string): TDatabaseProtocol => {
+    const { protocol } = new URL(databaseUrl);
+
+    if (protocol === 'mysql:' || protocol === 'mariadb:') return 'mariadb';
+    if (protocol === 'postgres:' || protocol === 'postgresql:') return 'postgresql';
+
+    throw new Error(
+        `Unsupported DATABASE_URL protocol "${protocol}". Proteum database diagnostics support mysql://, mariadb://, postgres://, and postgresql://.`,
+    );
+};
+
+const columnsFromMariaDbFields = (fields: unknown): TDatabaseReadQueryColumn[] =>
+    Array.isArray(fields)
+        ? fields.map((field) => {
+              const candidate = field as { name?: unknown; table?: unknown; type?: unknown };
+
+              return {
+                  name: typeof candidate.name === 'string' ? candidate.name : '',
+                  ...(typeof candidate.table === 'string' && candidate.table ? { table: candidate.table } : {}),
+                  ...(typeof candidate.type === 'number' || typeof candidate.type === 'string' ? { type: candidate.type } : {}),
+              };
+          })
+        : [];
+
+const readMariaDb = async ({
+    databaseUrl,
+    limit,
+    sql,
+    timeoutMs,
+}: {
+    databaseUrl: string;
+    limit: number;
+    sql: string;
+    timeoutMs: number;
+}) => {
+    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,
+    });
+
+    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);
+
+        return {
+            columns: columnsFromMariaDbFields(fields),
+            limited: normalizedRows.length > limit,
+            rowCount: normalizedRows.length,
+            rows: normalizedRows.slice(0, limit),
+        };
+    } catch (error) {
+        try {
+            await connection.rollback();
+        } catch (_rollbackError) {}
+
+        throw error;
+    } finally {
+        await connection.end();
+    }
+};
+
+const readPostgreSql = async ({
+    databaseUrl,
+    limit,
+    sql,
+    timeoutMs,
+}: {
+    databaseUrl: string;
+    limit: number;
+    sql: string;
+    timeoutMs: number;
+}) => {
+    const client = new PostgresClient({
+        connectionString: databaseUrl,
+        statement_timeout: timeoutMs,
+        query_timeout: timeoutMs,
+    });
+
+    try {
+        await client.connect();
+        await client.query('BEGIN READ ONLY');
+        await client.query('SET TRANSACTION READ ONLY');
+        const result = await client.query(sql);
+        await client.query('ROLLBACK');
+
+        const normalizedRows = result.rows.map(normalizeDatabaseRow);
+
+        return {
+            columns: result.fields.map((field) => ({
+                name: field.name,
+                ...(field.tableID ? { table: String(field.tableID) } : {}),
+                type: field.dataTypeID,
+            })),
+            limited: normalizedRows.length > limit,
+            rowCount: normalizedRows.length,
+            rows: normalizedRows.slice(0, limit),
+        };
+    } catch (error) {
+        try {
+            await client.query('ROLLBACK');
+        } catch (_rollbackError) {}
+
+        throw error;
+    } finally {
+        try {
+            await client.end();
+        } catch (_endError) {}
+    }
+};
+
+export const runDatabaseReadQuery = async ({
+    databaseUrl,
+    kind,
+    limit,
+    sql,
+    timeoutMs,
+}: {
+    databaseUrl: string;
+    kind: TDatabaseReadQueryResponse['kind'];
+    limit: number;
+    sql: string;
+    timeoutMs: number;
+}): Promise<TDatabaseReadQueryResponse> => {
+    const startedAt = performance.now();
+    const response =
+        databaseProtocolFromUrl(databaseUrl) === 'postgresql'
+            ? await readPostgreSql({ databaseUrl, limit, sql, timeoutMs })
+            : await readMariaDb({ databaseUrl, limit, sql, timeoutMs });
+    const elapsedMs = Math.max(0, Math.round(performance.now() - startedAt));
+
+    return {
+        ...response,
+        elapsedMs,
+        kind,
+        limit,
+        sql,
+    };
+};

package/server/app/devDiagnostics.ts

@@ -1,9 +1,8 @@
 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 { runDatabaseReadQuery } from './devDatabase';
 import type { TDevConsoleLogLevel, TDevConsoleLogsResponse } from '@common/dev/console';
 import {
     normalizeDatabaseReadLimit,
@@ -11,8 +10,6 @@ import {
     validateDatabaseReadQuery,
     type TDatabaseReadQueryInput,
     type TDatabaseReadQueryResponse,
-    type TDatabaseReadQueryRow,
-    type TDatabaseReadQueryValue,
 } from '@common/dev/database';
 import {
     buildDoctorResponse,
@@ -41,31 +38,12 @@ 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) {}
 
@@ -129,55 +107,8 @@ export default class DevDiagnosticsRegistry {
         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();
-        }
+        return runDatabaseReadQuery({ databaseUrl, kind, limit, sql, timeoutMs });
     }
 
     private resolveRequestTrace({ path, requestId }: { path?: string; requestId?: string }): TRequestTrace | undefined {

package/tests/agents-utils.test.cjs

@@ -102,12 +102,14 @@ test('standalone configure creates tracked instruction files with routing contra
     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, /central MCP ready banner/);
     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, /GEO\/SEO\/crawler\/structured-data\/AI-source changes/);
     assert.match(agentsContent, /MCP-selected previews are enough/);
     assert.doesNotMatch(agentsContent, /Conventional Commits/);
     assert.match(agentsContent, /They are not deleted/);

package/tests/cli-mcp-command.test.cjs

@@ -85,6 +85,63 @@ const runCli = async (args, { cwd }) =>
         child.once('close', (status) => resolve({ status, stdout, stderr }));
     });
 
+const waitForChildOutput = async (child, predicate, timeoutMs = 10000) =>
+    await new Promise((resolve, reject) => {
+        let output = '';
+        let settled = false;
+        let timer;
+        const cleanup = () => {
+            if (timer) clearTimeout(timer);
+            child.stdout.off('data', handleData);
+            child.stderr.off('data', handleData);
+            child.off('close', handleClose);
+        };
+        const settle = (callback) => {
+            if (settled) return;
+            settled = true;
+            cleanup();
+            callback();
+        };
+        const handleData = (chunk) => {
+            output += chunk.toString();
+            if (predicate(output)) settle(() => resolve(output));
+        };
+        const handleClose = (status, signal) => {
+            settle(() => reject(new Error(`Child exited before expected output. status=${status} signal=${signal}\n${output}`)));
+        };
+        timer = setTimeout(() => {
+            child.kill('SIGTERM');
+            settle(() => reject(new Error(`Timed out waiting for expected output.\n${output}`)));
+        }, timeoutMs);
+
+        child.stdout.on('data', handleData);
+        child.stderr.on('data', handleData);
+        child.once('close', handleClose);
+    });
+
+const writeLiveDaemonRecord = (registryDir, { port }) => {
+    const timestamp = new Date().toISOString();
+
+    writeFile(
+        path.join(registryDir, 'router.json'),
+        JSON.stringify(
+            {
+                version: 1,
+                pid: process.pid,
+                port,
+                host: '127.0.0.1',
+                mcpUrl: `http://127.0.0.1:${port}/mcp`,
+                healthUrl: `http://127.0.0.1:${port}/health`,
+                startedAt: timestamp,
+                updatedAt: timestamp,
+                command: [process.execPath, cliBin, 'mcp', '--daemon'],
+            },
+            null,
+            2,
+        ),
+    );
+};
+
 test('top-level help lists the machine-scope mcp router', () => {
     const result = spawnSync(process.execPath, [cliBin, '--help'], {
         cwd: coreRoot,
@@ -110,6 +167,54 @@ test('mcp help describes projectId routing', () => {
     assert.match(output, /--stdio/);
 });
 
+test('mcp daemon launch prints a central MCP connection banner', async () => {
+    const registryDir = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-mcp-daemon-launch-'));
+    const reserveServer = http.createServer((req, res) => res.end('reserved'));
+    const port = await listen(reserveServer);
+    await closeServer(reserveServer);
+    const child = spawn(process.execPath, [cliBin, 'mcp', '--daemon', '--port', String(port)], {
+        cwd: coreRoot,
+        env: { ...process.env, PROTEUM_MACHINE_MCP_DIR: registryDir },
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let closed = false;
+    child.once('close', () => {
+        closed = true;
+    });
+
+    try {
+        const output = await waitForChildOutput(child, (value) =>
+            value.includes(`Connect MCP client (HTTP): http://127.0.0.1:${port}/mcp`),
+        );
+
+        assert.match(output, /CENTRAL MCP READY/);
+        assert.match(output, /Launched central MCP server/);
+    } finally {
+        if (!closed) {
+            child.kill('SIGTERM');
+            await new Promise((resolve) => child.once('close', resolve));
+        }
+    }
+});
+
+test('mcp daemon reuse prints a central MCP connection banner', () => {
+    const registryDir = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-mcp-daemon-reuse-'));
+    const port = 37977;
+    writeLiveDaemonRecord(registryDir, { port });
+
+    const result = spawnSync(process.execPath, [cliBin, 'mcp', '--daemon', '--port', String(port)], {
+        cwd: coreRoot,
+        encoding: 'utf8',
+        env: { ...process.env, PROTEUM_MACHINE_MCP_DIR: registryDir },
+    });
+    const output = `${result.stdout}\n${result.stderr}`;
+
+    assert.equal(result.status, 0);
+    assert.match(output, /CENTRAL MCP READY/);
+    assert.match(output, /Connected to central MCP server/);
+    assert.match(output, new RegExp(`Connect MCP client \\(HTTP\\): http://127\\.0\\.0\\.1:${port}/mcp`));
+});
+
 test('db help describes read-only SQL diagnostics', () => {
     const result = spawnSync(process.execPath, [cliBin, 'db', '--help'], {
         cwd: coreRoot,

package/tests/mcp.test.cjs

@@ -25,6 +25,7 @@ const {
     normalizeDatabaseReadLimit,
     validateDatabaseReadQuery,
 } = require('../common/dev/database.ts');
+const { databaseProtocolFromUrl } = require('../server/app/devDatabase.ts');
 const { createProteumMachineMcpServer } = require('../cli/mcp/router.ts');
 const {
     createDevSessionRecord,
@@ -142,7 +143,18 @@ test('database read query policy allows only capped SELECT SHOW and EXPLAIN diag
     assert.throws(() => validateDatabaseReadQuery('UPDATE User SET role = "admin"'), /Only SELECT, SHOW, and EXPLAIN/);
     assert.throws(() => validateDatabaseReadQuery('SELECT 1; DROP TABLE User'), /Only one read-only SQL statement/);
     assert.throws(() => validateDatabaseReadQuery('EXPLAIN ANALYZE SELECT * FROM User'), /EXPLAIN ANALYZE/);
-    assert.throws(() => validateDatabaseReadQuery('SELECT LOAD_FILE("/etc/passwd")'), /LOAD_FILE/);
+    assert.throws(() => validateDatabaseReadQuery('SELECT LOAD_FILE("/etc/passwd")'), /file-read/);
+    assert.throws(() => validateDatabaseReadQuery("SELECT pg_read_file('/etc/passwd')"), /file-read/);
+    assert.throws(() => validateDatabaseReadQuery('SELECT * FROM "User" FOR SHARE'), /Locking read/);
+    assert.throws(() => validateDatabaseReadQuery('SELECT pg_sleep(1)'), /Sleep and benchmark/);
+});
+
+test('database diagnostics support MySQL MariaDB and PostgreSQL URLs', () => {
+    assert.equal(databaseProtocolFromUrl('mysql://user:pass@localhost:3306/app'), 'mariadb');
+    assert.equal(databaseProtocolFromUrl('mariadb://user:pass@localhost:3306/app'), 'mariadb');
+    assert.equal(databaseProtocolFromUrl('postgres://user:pass@localhost:5432/app'), 'postgresql');
+    assert.equal(databaseProtocolFromUrl('postgresql://user:pass@localhost:5432/app'), 'postgresql');
+    assert.throws(() => databaseProtocolFromUrl('sqlite://local.db'), /postgresql/);
 });
 
 test('instruction routing promotes triggered full instruction files', () => {