proteum 2.3.0 → 2.4.2

package/agents/project/app-root/AGENTS.md

@@ -3,7 +3,7 @@
 This file is the app-root-only addendum for a Proteum app that lives inside a larger monorepo.
 Keep the reusable Proteum contract in the nearest ancestor root `AGENTS.md`, and keep this file only for instructions that depend on the current directory being the Proteum app root.
 Role: keep only app-root workflow and local project-semantic rules here.
-Do not put here: reusable Proteum architecture contracts, shared verification rules, diagnostics workflow, optimization checklists, coding-style details, or area-specific rules already covered by broader `AGENTS.md` files or the root-level `diagnostics.md`, `optimizations.md`, and `CODING_STYLE.md`.
+Do not put here: reusable Proteum architecture contracts, shared verification rules, documentation-driven coding workflow, diagnostics workflow, optimization checklists, coding-style details, or area-specific rules already covered by broader `AGENTS.md` files or the root-level `DOCUMENTATION.md`, `diagnostics.md`, `optimizations.md`, and `CODING_STYLE.md`.
 
 ## App-Root Triggers
 
@@ -13,4 +13,4 @@ Do not put here: reusable Proteum architecture contracts, shared verification ru
   - Read and acknowledge the applicable `AGENTS.md` files.
   - Run `npm i`.
   - Run the dev server with the task-safe elevated-permissions launch workflow from the reusable root `AGENTS.md`, keep it running so user can see the results by himself, and print the live server URL as a clickable Markdown link. If `proteum dev` reports blocked instruction paths, resolve them before continuing.
-- If the task changes UX, copy, onboarding, pricing, product semantics, or commercial positioning, read the relevant files under `./docs/` first, especially `docs/PERSONAS.md`, `docs/PRODUCT.md`, and `docs/MARKETING.md` when they exist. If a dev server is already running, print the live dev server URL as a clickable Markdown link.
+- If the task changes UX, copy, onboarding, pricing, product semantics, or commercial positioning, use root-level `DOCUMENTATION.md` to choose the smallest relevant `./docs/` pack before editing. If a dev server is already running, print the live dev server URL as a clickable Markdown link.

package/agents/project/diagnostics.md

@@ -4,9 +4,9 @@ This file is the canonical source of truth for diagnostics, temporary instrument
 
 ## Initial Triage
 
-- Start with compact machine-readable app state before reading large parts of the codebase: `npx proteum orient <query>`, `npx proteum runtime status`, `npx proteum connect`, `npx proteum explain`, `npx proteum doctor`, and `npx proteum doctor --contracts` when generated artifacts or manifest-owned files may be stale.
-- When a Proteum MCP client is available, prefer MCP `runtime_status`, `orient`, `instructions_resolve`, `diagnose`, `trace_latest`, `perf_top`, `perf_request`, and `logs_tail` for repeated reads of the same app/runtime state. Use compact CLI commands when you need a reproducible shell command, validation step, or CI-like output.
-- MCP payloads are compact `proteum-mcp-v1` JSON and are capped/paginated by default. Do not request full detail until compact output identifies the missing data.
+- Start with compact machine-readable app state before reading large parts of the codebase. When a Proteum MCP client is available, 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`. Use the returned live `projectId` for follow-up MCP `runtime_status`, `orient`, `instructions_resolve`, `explain_summary`, `route_candidates`, `doctor`, `diagnose`, `trace_latest`, `trace_show`, `perf_top`, `perf_request`, `logs_tail`, and `db_query`.
+- 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 compact CLI commands such as `npx proteum orient <query>`, `npx proteum runtime status`, `npx proteum connect`, `npx proteum explain`, `npx proteum doctor`, and `npx proteum doctor --contracts` when MCP is unavailable, when generated artifacts or manifest-owned files may be stale, or when you need a reproducible shell command, validation step, or CI-like output.
+- MCP payloads are compact `proteum-mcp-v1` JSON and are capped/paginated by default. Use selected instruction previews for read-only discovery and diagnostics; read full files or request full MCP detail only when returned `fullRead`/`fullReadPolicy` or omitted-detail hints require it.
 - Use full-detail escape hatches only after compact output identifies the missing detail: `npx proteum explain --manifest`, `npx proteum diagnose <target> --full`, `npx proteum trace show <requestId> --events`, or `npx proteum perf request <requestId> --full`.
 - When the user pastes raw errors, reproduce locally before listing possible causes: identify the likely app, route, command, or request target from the error, boot or reuse the relevant dev server with the elevated-permissions workflow below, replay the failing surface once, and base the probability/why/how-to-fix list on local server output, browser console output, diagnostics, traces, or the smallest relevant command result. If there is not enough information to reproduce, state the missing context and ground the cause list in the local evidence that is available.
 - When one app depends on another app's generated controllers, inspect `npx proteum connect --controllers`, `npx proteum explain --connected --controllers`, the producer `proteum.connected.json`, the consumer `proteum.config.ts` connected `source` value, and the producer `./.proteum/proteum.connected.d.ts` before assuming the contract is local.
@@ -16,16 +16,17 @@ This file is the canonical source of truth for diagnostics, temporary instrument
 
 ## Runtime Diagnostics
 
-- 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 dev list --json` plus current listeners first, for example with `lsof -nP -iTCP -sTCP:LISTEN`, then choose a port that is not currently used before starting `npx proteum dev --session-file <path> --port <port>`. After the server is ready, print the live server URL as a clickable Markdown link.
+- 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.
 - 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.
-- For ownership or repo discovery questions, start with `npx proteum orient <query>` instead of jumping straight into source searches.
-- For request-time issues in dev, start with `npx proteum diagnose <path> --port <port>` when you have a concrete failing route, page, controller path, or request target. It combines owner lookup, manifest diagnostics, contract diagnostics, matching trace data, and buffered server logs in one pass.
+- 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.
+- For request-time issues in dev, start with MCP `diagnose { projectId, path }` when you have a concrete failing route, page, controller path, or request target. Use `npx proteum diagnose <path> --port <port>` only when MCP is unavailable or terminal evidence is required. It combines owner lookup, manifest diagnostics, contract diagnostics, matching trace data, and buffered server logs in one pass.
 - Prefer focused verification before global checks: `npx proteum verify owner <query>`, `npx proteum verify request <path>`, and only then browser MCP validation when the bug is browser-visible. Use `npx proteum e2e --port <port> ...` only when automated end-to-end coverage or a Playwright suite is required.
 - When diagnosing a consumer app that depends on local `file:` connected projects, boot every connected producer app too, each on its own free port and task-scoped session file, and run every one of those `proteum dev` processes with elevated permissions outside the sandbox before reproducing the consumer issue.
 - For connected-project failures, confirm the consumer app resolves the expected `connect.<Namespace>.source` and `connect.<Namespace>.urlInternal` values, the producer app exposes `GET /api/__proteum/connected/ping`, and the imported controller entries show `scope=connected` in `proteum explain`.
-- Use `npx proteum explain owner <query>` when you need a fast ownership graph for a route, controller path, source file, or generated artifact before reading code.
+- Use MCP `workflow_start`, `route_candidates { projectId, query }`, or `explain_summary { projectId, query }` when you need a fast ownership graph for a route, controller path, source file, or generated artifact before reading code. Use `npx proteum explain owner <query>` only when MCP is unavailable or terminal evidence is required. Do not use `npx proteum explain --routes --full` unless compact owner/route tools explicitly cannot answer a raw route-array question.
 - For performance issues or regressions in dev, use `npx proteum perf top --since <window>` to rank hot paths, `npx proteum perf request <requestId|path>` for one request waterfall plus chain attribution and SQL fingerprints, `npx proteum perf compare --baseline <window> --target <window>` for regressions, and `npx proteum perf memory --since <window>` for heap or RSS drift.
 - For bundle-size inspection, use `npx proteum build --prod --analyze` to emit `bin/bundle-analysis/client.html` and `client-stats.json`, or add `--analyze-serve --analyze-port auto` when you want a local analyzer URL instead of a static HTML file.
 - For request-time issues in dev, inspect traces before adding logs when the diagnose surface is still too coarse.
@@ -38,7 +39,7 @@ This file is the canonical source of truth for diagnostics, temporary instrument
 ## Temporary Instrumentation
 
 - When manifest inspection, trace data, browser console output, and server errors are still insufficient, add temporary targeted logs in the code to confirm control flow, payload shape, query shape, or branch selection.
-- If SQL is needed during diagnosis, keep it read-only. Never use SQL to change database structure or execute schema-mutating DDL.
+- If SQL is needed during diagnosis, use MCP `db_query { projectId, sql }` or `npx proteum db query "<sql>"` against a running dev server. Keep it read-only: only one capped `SELECT`, `SHOW`, or `EXPLAIN` statement is allowed, and the response includes rows, columns, elapsed milliseconds, and cap metadata. Never use SQL to change database structure or execute schema-mutating DDL.
 - Keep temporary logs narrow, contextual, and easy to remove. Do not leave broad debug noise in shared execution paths.
 - Re-run only the smallest relevant repro, request, or test after adding temporary instrumentation.
 - Temporary logs added in the code for diagnosis must be cleaned at the end of tests or the repro cycle and must never be committed.
@@ -57,7 +58,7 @@ This file is the canonical source of truth for diagnostics, temporary instrument
 - After implementing a change, verify at the smallest trustworthy layer required by the changed surface first, then run the full project `npx proteum check` before finishing. Do not default to a running app, browser MCP, or Playwright while iterating when a narrower static or request-level verification is enough.
 - For compile-time or type-safety issues, start with the relevant targeted typecheck or build command. Do not run them by default for unrelated runtime, copy, docs, or local refactor changes.
 - For request/runtime issues, verify through the real page, route, generated controller call, or command on a running app.
-- Start the smallest trustworthy runtime surface first: `npx proteum orient <query>`, then the relevant real URL, generated controller call, command, or `npx proteum diagnose <path> --port <port>`. Use browser MCP validation only when request-level verification is insufficient or the change is browser-visible.
+- Start the smallest trustworthy runtime surface first: MCP `workflow_start`, then MCP `route_candidates { projectId, query }`, MCP `orient { projectId, query }`, or MCP `explain_summary { projectId, query }` only when more owner detail is needed. If runtime health is unreachable, repair/start dev before any diagnose, trace, or perf read. Once runtime is reachable, use the relevant real URL, generated controller call, command, or MCP `diagnose { projectId, path }`. Use CLI equivalents only when MCP is unavailable or terminal evidence is required. Use browser MCP validation only when request-level verification is insufficient or the change is browser-visible.
 - When automated browser assertions or suite coverage are required, use `npx proteum e2e --port <port>` for targeted or full Playwright suites. Do not use direct Playwright for browser validation outside the E2E wrapper, and do not launch raw browser automation against a shared persistent profile.
 - Focused verification should treat unrelated global diagnostics as visible but non-blocking by default. Use `--strict-global` only when the task explicitly requires broad clean-room validation.
 - For browser regressions, prefer a browser MCP repro first and add targeted Playwright E2E coverage only when the user asks for automated coverage, when a stable regression path needs automation, or when browser MCP verification is insufficient.

package/agents/project/optimizations.md

@@ -19,7 +19,7 @@ When tradeoffs exist inside optimization work, optimize in this order:
 - Prefer established, flexible, well-typed, widely adopted, actively maintained packages.
 - Build custom or keep custom infrastructure only when packages would clearly hurt bundle size, SSR behavior, performance, typing quality, flexibility, licensing, explicit contracts, or long-term maintainability.
 - If you choose custom over a package, state briefly why.
-- For agent-facing repeated diagnostics, prefer the read-only Proteum MCP surface over adding broader CLI output. MCP should expose compact single-line `proteum-mcp-v1` JSON with capped, typed, paginated reads; the CLI should stay compact and reproducible.
+- For agent-facing repeated diagnostics, prefer the read-only Proteum MCP surface over adding broader CLI output. MCP should expose compact single-line `proteum-mcp-v1` JSON with capped, typed, paginated reads; the CLI should stay compact and reproducible. Database diagnostics are limited to one capped `SELECT`, `SHOW`, or `EXPLAIN` read through MCP `db_query` or CLI `proteum db query`.
 
 ## SSR And Page Size
 

package/agents/project/root/AGENTS.md

@@ -3,20 +3,24 @@
 This is the reusable Proteum-wide contract that is safe to place at the root of a monorepo above one or more Proteum apps.
 Pair this file with an app-root `AGENTS.md` inside each Proteum app when local workflow or product-context instructions depend on the current directory being the app root.
 Role: keep only reusable Proteum workflow, architecture contracts, shared typing rules, and cross-surface verification rules here.
-Do not put here: app-root bootstrap steps, local product-doc reading rules, detailed diagnostics workflow, optimization checklists, coding-style details, or narrow area-specific instructions that belong in `diagnostics.md`, `optimizations.md`, `CODING_STYLE.md`, `client/AGENTS.md`, `client/pages/AGENTS.md`, `server/routes/AGENTS.md`, `server/services/AGENTS.md`, or `tests/AGENTS.md`.
+Do not put here: app-root bootstrap steps, documentation-driven coding workflow, detailed diagnostics workflow, optimization checklists, coding-style details, or narrow area-specific instructions that belong in `DOCUMENTATION.md`, `diagnostics.md`, `optimizations.md`, `CODING_STYLE.md`, `client/AGENTS.md`, `client/pages/AGENTS.md`, `server/routes/AGENTS.md`, `server/services/AGENTS.md`, or `tests/AGENTS.md`.
 
+Documentation source of truth: root-level `DOCUMENTATION.md`.
 Optimization source of truth: root-level `optimizations.md`.
 Diagnostics source of truth: root-level `diagnostics.md`.
 Coding style source of truth: root-level `CODING_STYLE.md`.
 
+Managed compact root routers must use trigger -> canonical instruction file references, not copied summaries of this contract. If a trigger points here, load this full file before acting and keep the source rule here.
+
 ## 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 task is ambiguous, generated, connected, or multi-repo, start with `npx proteum orient <query>` before reading large parts of the codebase.
-- Treat Proteum CLI and MCP output as the workflow router. Read only the instruction files returned in `orient` `mustRead` or MCP `instructions_resolve`, plus conditional docs that match the current task. Do not read broad instruction folders or every managed instruction file up front.
-- When a Proteum MCP client is available, prefer read-only MCP tools for repeated runtime/status/orientation/trace/perf/log reads. Use CLI commands when you need reproducible terminal validation, dev/build/check workflows, or output to share with a human.
+- 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.
 - MCP payloads are compact single-line `proteum-mcp-v1` JSON with capped and paginated detail. Do not expand MCP output for human readability.
+- For every non-trivial coding task, load and follow root-level `DOCUMENTATION.md` before coding.
 - If the user reports an issue, or the agent encounters one during exploration, implementation, verification, or runtime reproduction, load and follow root-level `diagnostics.md`.
 - If the task touches client-side files, especially `client/**` and page files, load and apply root-level `optimizations.md` only after implementation for post-implementation checking and optimization. Skip it at task start and skip it for server-only, test-only, doc-only, and non-client refactor tasks unless the user explicitly asks for optimization work.
 - If the task needs new app or artifact boilerplate, prefer `npx proteum init ...` and `npx proteum create ...` before creating files by hand. Use `--dry-run --json` when an agent needs a machine-readable plan before writing files.
@@ -47,16 +51,18 @@ Coding style source of truth: root-level `CODING_STYLE.md`.
 ### During Implementation
 
 - After running `npx proteum create ...`, adapt the generated code to the real feature instead of leaving placeholder logic in place.
-- 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 dev list --json` plus current listeners first, for example with `lsof -nP -iTCP -sTCP:LISTEN`, then choose a port that is not currently used before starting `npx proteum dev --session-file <path> --port <port>`. After the server is ready, print the live server URL as a clickable Markdown link.
+- 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.
+- 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.
 
 ### 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.
 - 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:
@@ -173,7 +179,7 @@ Verify at the correct layer:
 - SSR changes: use the browser MCP to load the real page and inspect rendered HTML plus browser console.
 - Router or plugin changes: verify request context, auth, redirects, metrics, and validation on a running app.
 - New features or feature-behavior changes: use the cheapest trustworthy verification while iterating, use the browser MCP for browser-visible validation, then update the relevant end-to-end coverage and finish by running the full Playwright suite plus the full project `npx proteum check`.
-- Generated, connected, or ownership-ambiguous changes: start with `npx proteum orient <query>` and prefer `npx proteum verify owner <query>` before broad global checks.
+- Generated, connected, or ownership-ambiguous changes: start with MCP `workflow_start`, then `orient { projectId, query }` and `explain_summary { projectId, query }` only when more detail is needed; use `npx proteum orient <query>` and `npx proteum verify owner <query>` when MCP is unavailable or terminal evidence is required.
 - Browser-visible issues: use the browser MCP after request-level verification is insufficient. Use `npx proteum e2e --port <port> ...` only when automated end-to-end coverage or a Playwright suite is required.
 - Raw browser execution outside end-to-end suites: use the browser MCP only. Keep Playwright in `npx proteum e2e --port <port>` for targeted/full end-to-end suites.
 - For trace-first reproduction, session-based auth setup, temporary logs, and post-fix surface checks, follow root-level `diagnostics.md`.
@@ -216,6 +222,7 @@ Verify at the correct layer:
 ## Hard Stops
 
 - Never run schema-mutating SQL such as `ALTER TABLE`, `CREATE TABLE`, `DROP TABLE`, or `CREATE INDEX` to change database structure.
+- For read-only SQL diagnosis, use MCP `db_query` or `npx proteum db query "<sql>"`; only one capped `SELECT`, `SHOW`, or `EXPLAIN` statement is allowed.
 - Do not run `prisma *` yourself. If a schema change requires migration, ask the user to run `npx prisma migrate dev --config ./prisma.config.ts --name <migration name>` and wait for `continue`.
 - Do not run `git restore` or `git reset`.
 - Do not run write-mode git commands by default. The built-in exception is an exact `commit` reply, which allows `git add` and `git commit` in every affected repository or worktree touched during the whole conversation. Any other write-mode git action requires an explicit user request.
@@ -271,10 +278,10 @@ Prefer structured CLI surfaces over re-deriving framework facts from source:
 - `npx proteum orient <query>`
 - `npx proteum runtime status`
 - `npx proteum mcp`
-- `npx proteum mcp --url http://localhost:<port>`
 - `npx proteum explain`
 - `npx proteum explain --manifest`
 - `npx proteum explain --connected --controllers`
+- `npx proteum explain --connected --controllers --full` only when raw connected/controller arrays are required
 - `npx proteum explain owner <query>`
 - `npx proteum doctor`
 - `npx proteum doctor --contracts`

package/agents/project/server/services/AGENTS.md

@@ -31,6 +31,7 @@ Diagnostics source of truth: root-level `diagnostics.md`.
 - In database queries, prefer explicit `select` or narrow `include`.
 - For database structure changes, edit the app's `schema.prisma` only. Never create or edit migration files manually.
 - Never use raw SQL DDL or other schema-mutating SQL to change database structure.
+- For read-only SQL diagnosis, use MCP `db_query` or `npx proteum db query "<sql>"`; only one capped `SELECT`, `SHOW`, or `EXPLAIN` statement is allowed.
 - Prefer inferred return types such as `Awaited<ReturnType<MyService['methodName']>>` over manual DTO duplication.
 
 ## Errors

package/agents/project/tests/AGENTS.md

@@ -9,6 +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.
 - 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/db.ts

@@ -0,0 +1,160 @@
+import fs from 'fs-extra';
+import got from 'got';
+import path from 'path';
+import { UsageError } from 'clipanion';
+
+import cli from '..';
+import {
+    defaultDatabaseReadTimeoutMs,
+    maxDatabaseReadLimit,
+    maxDatabaseReadTimeoutMs,
+    type TDatabaseReadQueryResponse,
+} from '../../common/dev/database';
+import { printAgentResponse, printJson, quoteCommandArgument } from '../utils/agentOutput';
+
+type TDbAction = 'query';
+
+const allowedActions = new Set<TDbAction>(['query']);
+const normalizeBaseUrl = (value: string) => value.replace(/\/+$/, '');
+
+const getRouterPortFromManifest = () => {
+    const manifestFilepath = path.join(cli.args.workdir as string, '.proteum', 'manifest.json');
+    if (!fs.existsSync(manifestFilepath)) return undefined;
+
+    const manifest = fs.readJsonSync(manifestFilepath, { throws: false }) as
+        | { env?: { resolved?: { routerPort?: number } } }
+        | undefined;
+    const port = manifest?.env?.resolved?.routerPort;
+
+    if (typeof port !== 'number' || port <= 0) return undefined;
+
+    return String(port);
+};
+
+const getRouterPort = () => {
+    const overridePort = typeof cli.args.port === 'string' && cli.args.port ? cli.args.port : '';
+    if (overridePort) return overridePort;
+
+    const envPort = process.env.PORT?.trim();
+    if (envPort) return envPort;
+
+    const manifestPort = getRouterPortFromManifest();
+    if (manifestPort) return manifestPort;
+
+    throw new UsageError(
+        `Could not determine the router port from PORT or .proteum/manifest.json in ${cli.args.workdir as string}. Pass --port or --url explicitly.`,
+    );
+};
+
+const getRouterBaseUrls = () => {
+    const explicitUrl = typeof cli.args.url === 'string' && cli.args.url ? cli.args.url.trim() : '';
+    if (explicitUrl) return [normalizeBaseUrl(explicitUrl)];
+
+    const port = getRouterPort();
+    return [...new Set([`http://127.0.0.1:${port}`, `http://localhost:${port}`, `http://[::1]:${port}`])];
+};
+
+const parsePositiveInteger = (value: unknown, label: string, max: number) => {
+    if (typeof value !== 'string' || !value.trim()) return undefined;
+
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed <= 0) throw new UsageError(`${label} must be a positive integer.`);
+    if (parsed > max) throw new UsageError(`${label} must be ${max} or lower.`);
+
+    return parsed;
+};
+
+const requestJson = async <TResponse>(pathname: string, json: object) => {
+    const attempts: string[] = [];
+
+    for (const baseUrl of getRouterBaseUrls()) {
+        try {
+            const response = await got(`${baseUrl}${pathname}`, {
+                method: 'POST',
+                json,
+                responseType: 'json',
+                retry: { limit: 0 },
+                throwHttpErrors: false,
+            });
+
+            if (response.statusCode >= 400) {
+                const body = response.body as { error?: string } | undefined;
+                throw new UsageError(body?.error || `Database query failed with status ${response.statusCode}.`);
+            }
+
+            return response.body as TResponse;
+        } catch (error) {
+            if (error instanceof UsageError) throw error;
+
+            const message = error instanceof Error ? error.message : String(error);
+            attempts.push(`${baseUrl}${pathname}: ${message}`);
+        }
+    }
+
+    throw new UsageError(
+        [
+            'Could not reach the Proteum database diagnostics server.',
+            ...attempts.map((attempt) => `- ${attempt}`),
+            'Make sure the app is running with `proteum dev`, or pass `--url http://host:port` if it is bound elsewhere.',
+        ].join('\n'),
+    );
+};
+
+const buildFullCommand = (sql: string) =>
+    [
+        'proteum db query',
+        quoteCommandArgument(sql),
+        typeof cli.args.limit === 'string' && cli.args.limit ? `--limit ${cli.args.limit}` : '',
+        typeof cli.args.timeout === 'string' && cli.args.timeout ? `--timeout ${cli.args.timeout}` : '',
+        typeof cli.args.port === 'string' && cli.args.port ? `--port ${cli.args.port}` : '',
+        typeof cli.args.url === 'string' && cli.args.url ? `--url ${quoteCommandArgument(cli.args.url)}` : '',
+        '--full',
+    ]
+        .filter(Boolean)
+        .join(' ');
+
+export const run = async () => {
+    const action = typeof cli.args.action === 'string' && cli.args.action ? cli.args.action : 'query';
+    if (!allowedActions.has(action as TDbAction)) {
+        throw new UsageError(`Unsupported db action "${action}". Expected: query.`);
+    }
+
+    const sql = typeof cli.args.sql === 'string' ? cli.args.sql.trim() : '';
+    if (!sql) throw new UsageError('A SELECT, SHOW, or EXPLAIN SQL statement is required.');
+
+    const limit = parsePositiveInteger(cli.args.limit, '--limit', maxDatabaseReadLimit);
+    const timeoutMs = parsePositiveInteger(cli.args.timeout, '--timeout', maxDatabaseReadTimeoutMs);
+    const response = await requestJson<TDatabaseReadQueryResponse>('/__proteum/db/query', {
+        sql,
+        ...(limit !== undefined ? { limit } : {}),
+        ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+    });
+
+    if (cli.args.full === true) {
+        printJson(response);
+        return;
+    }
+
+    printAgentResponse({
+        summary: `${response.kind.toUpperCase()} returned ${response.rows.length}/${response.rowCount} rows in ${response.elapsedMs} ms${response.limited ? ` (limited to ${response.limit})` : ''}.`,
+        data: {
+            kind: response.kind,
+            elapsedMs: response.elapsedMs,
+            rowCount: response.rowCount,
+            returnedRowCount: response.rows.length,
+            limit: response.limit,
+            limited: response.limited,
+            columns: response.columns,
+            rows: response.rows,
+        },
+        fullDetailCommand: buildFullCommand(sql),
+        omitted: response.limited
+            ? [
+                  {
+                      reason: `Rows are capped at ${response.limit}. Raise --limit up to ${maxDatabaseReadLimit} or narrow the query for more detail.`,
+                      command: `proteum db query ${quoteCommandArgument(sql)} --limit ${Math.min(response.limit * 2, maxDatabaseReadLimit)} --timeout ${timeoutMs || defaultDatabaseReadTimeoutMs}`,
+                  },
+              ]
+            : undefined,
+    });
+};

package/cli/commands/dev.ts

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

package/cli/commands/diagnose.ts

@@ -187,6 +187,7 @@ const renderOrientation = (response: TDiagnoseResponse) =>
         : [
               'Orientation',
               `- agents=${response.orientation.guidance.agents}`,
+              `- documentation=${response.orientation.guidance.documentation}`,
               `- diagnostics=${response.orientation.guidance.diagnostics}`,
               `- optimizations=${response.orientation.guidance.optimizations}`,
               `- codingStyle=${response.orientation.guidance.codingStyle}`,
@@ -343,6 +344,7 @@ const printCompactDiagnose = ({
             instructions: response.orientation
                 ? {
                       mustRead: [...new Set([response.orientation.guidance.agents, ...response.orientation.guidance.areaAgents])],
+                      documentation: response.orientation.guidance.documentation,
                       diagnostics: response.orientation.guidance.diagnostics,
                       codingStyle: response.orientation.guidance.codingStyle,
                       optimizations: response.orientation.guidance.optimizations,