proteum 2.3.0 → 2.4.2

package/common/dev/mcpServer.ts

@@ -7,6 +7,7 @@ import { stringifyMcpPayload, type TProteumMcpPayload } from './mcpPayloads';
 export type TProteumMcpDetail = 'compact' | 'full';
 
 export type TProteumMcpProvider = {
+    dbQuery: (input: { limit?: number; sql: string; timeoutMs?: number }) => Promise<TProteumMcpPayload>;
     diagnose: (input: {
         logsLevel?: 'silly' | 'log' | 'info' | 'warn' | 'error';
         logsLimit?: number;
@@ -22,9 +23,11 @@ export type TProteumMcpProvider = {
     perfRequest: (input: { query: string }) => Promise<TProteumMcpPayload>;
     perfTop: (input: { groupBy?: 'path' | 'route' | 'controller'; limit?: number; since?: string }) => Promise<TProteumMcpPayload>;
     readResource: (uri: string) => Promise<TProteumMcpPayload>;
+    routeCandidates: (input: { limit?: number; query: string }) => Promise<TProteumMcpPayload>;
     runtimeStatus: (input: Record<string, never>) => Promise<TProteumMcpPayload>;
     traceLatest: (input: { detail?: TProteumMcpDetail; limit?: number; offset?: number }) => Promise<TProteumMcpPayload>;
     traceShow: (input: { detail?: TProteumMcpDetail; limit?: number; offset?: number; requestId: string }) => Promise<TProteumMcpPayload>;
+    workflowStart: (input: { file?: string; query?: string; route?: string; task?: string }) => Promise<TProteumMcpPayload>;
 };
 
 type TCreateProteumMcpServerArgs = {
@@ -62,6 +65,8 @@ const detailSchema = z.enum(['compact', 'full']).optional();
 const logsLevelSchema = z.enum(['silly', 'log', 'info', 'warn', 'error']).optional();
 const positiveLimitSchema = z.number().int().min(1).max(100).optional();
 const offsetSchema = z.number().int().min(0).max(10_000).optional();
+const databaseLimitSchema = z.number().int().min(1).max(500).optional();
+const databaseTimeoutSchema = z.number().int().min(100).max(30_000).optional();
 
 export const createProteumMcpServer = ({ provider, version }: TCreateProteumMcpServerArgs) => {
     const server = new McpServer(
@@ -76,6 +81,23 @@ export const createProteumMcpServer = ({ provider, version }: TCreateProteumMcpS
         },
     );
 
+    server.registerTool(
+        'workflow_start',
+        {
+            annotations: readOnlyAnnotations,
+            description:
+                'Bootstrap an agent workflow with compact runtime, instruction, owner, doctor, and next-action data in one read.',
+            inputSchema: {
+                file: z.string().optional().describe('Optional source file or generated artifact path in scope.'),
+                query: z.string().optional().describe('Optional task, route, controller, file, or owner query.'),
+                route: z.string().optional().describe('Optional route path in scope.'),
+                task: z.string().optional().describe('Optional short natural-language task description.'),
+            },
+            title: 'Proteum Workflow Start',
+        },
+        async ({ file, query, route, task }) => jsonToolResult(await provider.workflowStart({ file, query, route, task })),
+    );
+
     server.registerTool(
         'runtime_status',
         {
@@ -126,6 +148,20 @@ export const createProteumMcpServer = ({ provider, version }: TCreateProteumMcpS
         async ({ query }) => jsonToolResult(await provider.explainSummary({ query })),
     );
 
+    server.registerTool(
+        'route_candidates',
+        {
+            annotations: readOnlyAnnotations,
+            description: 'Return compact route candidates for a query without dumping raw route arrays.',
+            inputSchema: {
+                limit: z.number().int().min(1).max(50).optional(),
+                query: z.string().min(1).describe('Route path or route-like search query.'),
+            },
+            title: 'Proteum Route Candidates',
+        },
+        async ({ limit, query }) => jsonToolResult(await provider.routeCandidates({ limit, query })),
+    );
+
     server.registerTool(
         'doctor',
         {
@@ -231,6 +267,21 @@ export const createProteumMcpServer = ({ provider, version }: TCreateProteumMcpS
         async ({ level, limit }) => jsonToolResult(await provider.logsTail({ level, limit })),
     );
 
+    server.registerTool(
+        'db_query',
+        {
+            annotations: readOnlyAnnotations,
+            description: 'Run one capped read-only database diagnostic query. Only SELECT, SHOW, and EXPLAIN are allowed.',
+            inputSchema: {
+                limit: databaseLimitSchema,
+                sql: z.string().min(1).describe('One SELECT, SHOW, or EXPLAIN SQL statement.'),
+                timeoutMs: databaseTimeoutSchema,
+            },
+            title: 'Proteum Database Query',
+        },
+        async ({ limit, sql, timeoutMs }) => jsonToolResult(await provider.dbQuery({ limit, sql, timeoutMs })),
+    );
+
     for (const [name, uri, description] of [
         ['runtime-status', 'proteum://runtime/status', 'Current compact runtime status.'],
         ['instructions-router', 'proteum://instructions/router', 'Current instruction routing contract.'],

package/docs/agent-routing.md

@@ -6,15 +6,17 @@ The optimized stack is:
 
 - routed agent instructions for stable policy
 - compact CLI for reproducible command-line checks
-- MCP for repeated reads of the same project/runtime state
+- MCP for repeated reads of the same project/runtime state, routed by `projectId`
 
 The routing strategy is:
 
 1. Use instructions for hard safety rules and routing only.
-2. Use MCP when available for repeated reads, runtime status, instruction routing, traces, perf, and logs.
-3. Use `proteum orient <query>` or the MCP `orient` tool to resolve the task-specific owner, `mustRead` instruction files, and next command.
-4. Use compact CLI output for reproducible terminal validation and CI-like checks.
-5. Use `--full`, `--manifest`, `--events`, or MCP paginated `detail: "full"` only after compact output identifies the missing detail.
+2. Use MCP first when available for read-only runtime status, instruction routing, owner lookup, diagnosis, traces, perf, and logs.
+3. Start machine MCP sessions with `workflow_start { cwd, task, route?, file? }` when possible; use `project_resolve { cwd }` when the bootstrap is ambiguous, no `projectId` is known, or the app is offline.
+4. Pass the returned live stable `projectId` to every follow-up app-bound MCP call.
+5. Use MCP `orient { projectId, query }`, `instructions_resolve { projectId, query }`, `route_candidates { projectId, query }`, and `explain_summary { projectId, query }` only when `workflow_start` did not return enough owner or instruction detail.
+6. Use compact CLI output for reproducible terminal validation, CI-like checks, fallback repair, and final evidence.
+7. Use `--full`, `--manifest`, `--events`, or MCP paginated `detail: "full"` only after compact output identifies the missing detail.
 
 ## Problem Resolved
 
@@ -28,7 +30,7 @@ The measured Product diagnostic loop produced roughly tens of thousands of outpu
 - raw `trace latest`
 - `perf request`
 - `verify request`
-- sometimes full `explain --json`
+- sometimes full manifest or explain section output
 
 Managed project instructions also embedded the same Proteum corpus into multiple generated files, so reading a handful of local docs could repeat the same contract many times.
 
@@ -48,7 +50,7 @@ Default CLI output for agent commands is compact `proteum-agent-v1` JSON:
 }
 ```
 
-Use the compact commands first:
+Use compact CLI commands when MCP is unavailable, when a command must be reproducible in a shell, or when final terminal evidence is required:
 
 ```bash
 proteum orient <route|file|controller|error>
@@ -60,19 +62,15 @@ proteum trace latest
 
 Use MCP for repeated reads when a client is available:
 
-```bash
+```text
 proteum mcp
-proteum mcp --url http://localhost:3101
-proteum mcp --session-file var/run/proteum/dev/agents/task.json
 ```
 
-During `proteum dev`, the same read-only tool contract is available at:
+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.
 
-```text
-http://localhost:<port>/__proteum/mcp
-```
+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`.
 
-Prefer the dev-hosted MCP endpoint when the app is already running; prefer stdio `proteum mcp` when the agent environment launches MCP servers itself. Prefer CLI over MCP when the result must be reproducible as a shell command, part of verification, or copied into CI/debug instructions.
+Prefer CLI over MCP when the result must be reproducible as a shell command, part of verification, or copied into CI/debug instructions.
 
 MCP output is compact `proteum-mcp-v1` JSON. It is intentionally single-line JSON, capped, and paginated for full trace detail. Do not expand MCP output just to make it look nicer for humans.
 
@@ -80,6 +78,7 @@ Use full-detail escape hatches only when needed:
 
 ```bash
 proteum explain --manifest
+proteum explain --routes --controllers --full
 proteum orient <query> --full
 proteum diagnose <target> --full
 proteum trace show <requestId> --events
@@ -90,8 +89,21 @@ proteum perf request <requestId> --full
 
 Managed `AGENTS.md` files now carry a compact router instead of the full instruction corpus.
 
+The router standard is trigger -> canonical instruction file, not trigger -> copied summary. Keep the compact root focused on hard safety rules, routing triggers, and source-map references. When a trigger needs a lifecycle or area contract, route agents to the full file that owns the rule.
+
+Standard triggered reads:
+
+- Git lifecycle (`commit`, `and commit`, `stage`, `push`, `PR`, pull request): root contract fallback.
+- Before finishing production code changes: root contract fallback, `CODING_STYLE.md`, and touched area `AGENTS.md`.
+- Runtime-visible, request-time, router, SSR, browser, or controller behavior: root contract fallback plus `diagnostics.md`.
+- Non-trivial feature, product, business-rule, UX, copy, or docs changes: `DOCUMENTATION.md`.
+- Implementation edits: `CODING_STYLE.md` plus the matching area file from the routing table.
+
+`workflow_start`, `orient`, `route_candidates`, and MCP `instructions_resolve` should promote obvious triggered files into selected instruction previews; ambiguous conditional reads can remain in `readWhen`.
+
 Area files carry only their own source content:
 
+- `DOCUMENTATION.md`: documentation-driven coding, `/docs` source-of-truth routing, and docs update expectations
 - `diagnostics.md`: raw errors, failing routes, traces, perf, reproduction
 - `optimizations.md`: package, runtime, build, and optimization decisions
 - `CODING_STYLE.md`: implementation style before editing
@@ -102,9 +114,9 @@ Area files carry only their own source content:
 - `tests/e2e/AGENTS.md`: E2E workflow
 - `tests/e2e/REAL_WORLD_JOURNEY_TESTS.md`: journey-test design
 
-Agents should not read broad folders or every managed instruction file. They should read only `mustRead` from `orient`, plus conditional docs that match the current task.
+Agents should not read broad folders or every managed instruction file. They should use selected MCP previews for read-only discovery and diagnostics, then read full files only before edits or git writes, when returned `fullRead`/`fullReadPolicy` requires it, or when the preview is insufficient.
 
-The MCP `instructions_resolve` resource/tool exposes the same routing decision in compact JSON and is the lowest-token way to refresh instruction selection without rereading full docs.
+MCP `workflow_start` exposes the first routing decision in compact JSON. MCP `instructions_resolve { projectId, query }` is the lowest-token way to refresh instruction selection without rereading full docs.
 
 ## Benchmark Result
 
@@ -114,13 +126,12 @@ The latest Product `/domains` benchmark used routed instructions plus the compac
 | --- | ---: | ---: |
 | Compact CLI single loop | 6,286 | 4,809 ms |
 | Dev-hosted HTTP MCP single loop | 5,211 | 232 ms |
-| Stdio MCP single loop | 5,526 | 900 ms |
 | Compact CLI repeated reads x3 | 11,660 | 9,572 ms |
 | Dev-hosted HTTP MCP repeated reads x3 | 10,537 | 214 ms |
 
 The result confirms the intended routing:
 
 - use CLI for reproducible verification and final command evidence
-- use dev-hosted MCP for repeated runtime reads against an already running app
-- use stdio MCP when the agent needs a launchable MCP server from an app/worktree
-- use `instructions_resolve` to refresh routing instead of rereading instruction files
+- use `workflow_start` to collapse project resolution, runtime status, instruction previews, owner summary, and first next actions into one read
+- use machine MCP with `projectId` for repeated runtime reads against an already running app
+- use `instructions_resolve` to refresh routing instead of rereading full instruction files

package/docs/dev-commands.md

@@ -79,7 +79,7 @@ The profiler also exposes the shared diagnostics surfaces for humans:
 
 For the shared diagnostics contract, trace-derived perf contract, and the corresponding dev HTTP endpoints, see [diagnostics.md](diagnostics.md) and [request-tracing.md](request-tracing.md).
 
-Command execution stays in the CLI, profiler, and dev command HTTP endpoints. The Proteum MCP surfaces are read-only; use MCP for repeated diagnostics, trace, perf, status, and log reads, not for running commands.
+Command execution stays in the CLI, profiler, and dev command HTTP endpoints. The Proteum MCP surfaces are read-only; use MCP with the selected `projectId` for repeated diagnostics, trace, perf, status, and log reads, not for running commands.
 
 ### HTTP Endpoints
 

package/docs/dev-sessions.md

@@ -78,7 +78,7 @@ curl -H "$(jq -r '.curlCookieHeader' session.json)" http://localhost:3101/api/Au
 - Prefer `proteum session` over UI login automation when the goal is to test or debug protected application behavior.
 - Prefer `proteum verify browser` for focused browser-visible verification, and `proteum e2e --port <port>` for targeted or full Playwright suites. When lower-level control is required, use direct Playwright with a disposable profile.
 - Use UI login automation only when the auth UX itself is the feature under test.
-- Pair it with `proteum diagnose` for a fast protected-route summary, `proteum perf request` for a one-request timing breakdown, or MCP `diagnose`/`perf_request` for repeated reads against the same running app. Use `proteum trace show <requestId> --events` only when you need lower-level request events.
+- Pair it with `proteum diagnose` for a fast protected-route summary, `proteum perf request` for a one-request timing breakdown, or MCP `diagnose`/`perf_request` with the selected `projectId` for repeated reads against the same running app. Use `proteum trace show <requestId> --events` only when you need lower-level request events.
 - Only the final verifier agent should usually run browser flows. Earlier agents should stay on `orient`, `verify owner`, `verify request`, and request-level diagnostics unless browser execution is required.
 
 Typical flow:
@@ -93,6 +93,8 @@ proteum perf request /dashboard --port 3101
 proteum trace latest --port 3101
 ```
 
+Use the exact next action from `proteum runtime status` before starting a long-lived dev server. It inspects configured router/HMR ports without fetching normal page bodies, and it tells agents to use or repair an untracked same-app runtime instead of starting a second server.
+
 When `proteum verify browser <path>` is available in the target app, it uses the same fresh per-run browser workspace model under `var/proteum/browser/<run-id>` and should be preferred over ad hoc shared Playwright profile reuse.
 
 ## Dev HTTP Endpoint

package/docs/diagnostics.md

@@ -13,7 +13,7 @@ Performance inspection is a sibling surface, not a separate instrumentation stac
 
 The diagnostics and routing CLI surfaces are optimized for agents by default. They return compact decision-ready output first and expose large raw detail only through explicit flags such as `--full`, `--manifest`, or `--events`.
 
-For repeated agent reads, Proteum also exposes the same compact diagnostic contract through MCP. Use `proteum mcp` for stdio clients and `/__proteum/mcp` from a running `proteum dev` server for runtime-adjacent data. See [mcp.md](mcp.md).
+For repeated agent reads, Proteum also exposes the same compact diagnostic contract through `proteum mcp`, a machine-scope router that forwards `projectId`-scoped calls to the matching dev-hosted `/__proteum/mcp` endpoint. See [mcp.md](mcp.md).
 
 ## Shared Contract
 
@@ -22,12 +22,12 @@ The canonical snapshot lives in `./.proteum/manifest.json`.
 Proteum uses that same manifest in these places:
 
 - `proteum orient` for owner lookup, guidance resolution, connected-boundary summary, and next-step suggestions
-- `proteum explain` for human-readable and `--json` output
+- `proteum explain` for compact manifest summaries and selected-section counts
 - `proteum doctor` for human-readable and `--json` output
 - `proteum explain owner <query>` for ownership lookup over the manifest index
 - `proteum doctor --contracts` for generated-artifact and manifest-owned source validation on disk
 - the dev-only `__proteum/explain*` and `__proteum/doctor*` HTTP endpoints
-- the dev-only `/__proteum/mcp` endpoint and `proteum mcp` stdio server
+- the dev-only `/__proteum/mcp` endpoint
 - the `Explain`, `Doctor`, and `Diagnose` tabs in the bottom profiler during `proteum dev`
 
 This means the CLI, MCP, the dev HTTP endpoints, and the profiler all describe the same framework-owned snapshot before any live trace or log overlays are added.
@@ -44,6 +44,7 @@ proteum orient /api/Auth/CurrentUser
 proteum explain
 proteum explain owner /api/Auth/CurrentUser
 proteum explain --routes --controllers --commands
+proteum explain --routes --controllers --commands --full
 proteum explain --manifest
 
 proteum doctor
@@ -66,9 +67,6 @@ proteum perf compare --baseline yesterday --target today --group-by route
 proteum perf memory --since 1h --group-by controller
 
 proteum runtime status
-proteum mcp
-proteum mcp --url http://localhost:3101
-proteum mcp --session-file var/run/proteum/dev/agents/task.json
 ```
 
 Default compact command output follows this shape:
@@ -98,7 +96,7 @@ Default compact command output follows this shape:
 
 `proteum orient --full` emits the full orientation payload.
 
-`proteum explain` emits a compact manifest summary. `proteum explain --manifest` emits the full generated manifest, and explicit section flags such as `--routes --controllers` emit those sections.
+`proteum explain` emits a compact manifest summary. Explicit section flags such as `--routes --controllers` now summarize those sections by default to avoid route/controller dumps in agent context. Add `--full` to emit selected raw section arrays, or use `proteum explain --manifest` for the full generated manifest.
 
 `proteum explain owner <query>` emits compact owner ranking. `proteum explain owner <query> --full` keeps the existing full owner ranking shape and adds:
 
@@ -112,9 +110,9 @@ Default compact command output follows this shape:
 - `summary.strictFailed`
 - `diagnostics`
 
-`proteum runtime status` emits the current app manifest summary, tracked dev sessions, selected live session, health status, and a suggested next command. Use it before starting another dev server.
+`proteum runtime status` emits the current app manifest summary, tracked dev sessions, selected live session, MCP URL, health status, configured router/HMR port inspection, and a suggested next command. Use it before starting another dev server, and use its Start Dev command instead of probing page bodies when the default port is occupied. If it reports that the same app already responds on the configured port without a live tracked session, use or repair that runtime instead of starting a second server.
 
-`proteum mcp` starts the read-only stdio MCP server. It exposes compact `runtime_status`, `orient`, `instructions_resolve`, `explain_summary`, `doctor`, `diagnose`, `trace_*`, `perf_*`, and `logs_tail` tools without spawning CLI commands for each read.
+During `proteum dev`, `/__proteum/mcp` exposes compact `workflow_start`, `runtime_status`, `orient`, `instructions_resolve`, `route_candidates`, `explain_summary`, `doctor`, `diagnose`, `trace_*`, `perf_*`, and `logs_tail` tools without spawning CLI commands for each repeated read. `proteum dev` also ensures one managed machine `proteum mcp` daemon is running. Through the machine router, call `workflow_start` with `cwd` or a known `projectId`; if routing is ambiguous or returns offline app candidates, use `project_resolve { cwd }`, follow the selected app root's port-inspected next action when needed, then pass the selected live `projectId` to follow-up app-bound tools.
 
 MCP tool/resource output follows compact single-line `proteum-mcp-v1` JSON:
 
@@ -211,7 +209,7 @@ GET /__proteum/diagnose?query=/api/Auth/CurrentUser&logsLevel=warn&logsLimit=40
 
 These endpoints are intended for local tooling and are not available in production.
 
-`/__proteum/mcp` is the dev-hosted MCP transport. It exposes the same read-only tool/resource contract as `proteum mcp`, backed directly by the running app's diagnostics, trace, perf, and log stores. The `proteum dev` session UI and ready banner print this URL when the server is ready.
+`/__proteum/mcp` is the dev-hosted MCP transport. It exposes the read-only tool/resource contract backed directly by the running app's diagnostics, trace, perf, and log stores. The `proteum dev` session UI and ready banner print this URL when the server is ready. The machine `proteum mcp` router discovers these live endpoints and routes app-bound calls by `projectId`.
 
 ## Profiler
 
@@ -251,13 +249,16 @@ Treat these as framework contract failures first. The fix usually belongs at the
 
 For AI coding agents or automation:
 
-1. Start with `proteum orient <query>` or MCP `orient` when the target might be generated, connected, framework-owned, multi-repo, or instruction-ambiguous.
-2. Read only `instructions.mustRead` from compact orientation output, or use MCP `instructions_resolve` to refresh the routed instruction set without rereading docs.
-3. Run `proteum runtime status` before starting another dev server; use MCP `runtime_status` for repeated status reads.
-4. Use `proteum diagnose <path> --port <port>` or MCP `diagnose` for the smallest trustworthy runtime surface before broad checks.
-5. Use `proteum perf request <requestId|path>` or MCP `perf_request` for performance, CPU, SQL, render, cache, or connected-boundary questions.
-6. Use `proteum trace show <requestId> --events` only when compact diagnose, perf, trace, or MCP output says lower-level event detail is needed.
-7. Use `proteum explain --manifest` or read `./.proteum/manifest.json` only when compact `orient`/`explain`/MCP summary cannot answer the specific manifest question.
-8. Use `proteum verify browser` for browser-visible verification, or `proteum e2e --port <port>` for targeted/full Playwright suites. Keep auth sourced from Proteum session helpers.
-9. Run global checks second, not first. Unrelated diagnostics should remain visible but non-blocking during focused verification unless strict global mode is required.
-10. Open the profiler only when a human-readable view helps; it should agree with the CLI and MCP after refresh.
+1. When MCP is available, call `workflow_start` with `cwd` or a known `projectId`; if routing is ambiguous or returns offline app candidates, call `project_resolve { cwd }`, select the intended app root, start dev from that app root when needed, then retry with the selected stable live `projectId`.
+2. Use the returned `projectId` for MCP `runtime_status`, `orient`, `instructions_resolve`, `route_candidates`, `explain_summary`, `doctor`, `diagnose`, `trace_show`, `perf_request`, and `logs_tail` read-only runtime, owner, route, instruction, trace, perf, and log reads.
+3. Do not run CLI equivalents after a successful MCP result for the same read, and do not run broad source searches for ownership MCP already returned. Use CLI for fallback, `dev`, `build`, `check`, `verify`, migrations, E2E, and final terminal evidence.
+4. Use selected instruction previews for read-only discovery and diagnostics; read full files only before edits or git writes, when returned `fullRead`/`fullReadPolicy` requires it, or when the preview is insufficient.
+5. Use `proteum orient <query>` only when MCP is unavailable or terminal evidence is required.
+6. If machine MCP routing fails, run `proteum mcp status` and `proteum runtime status` from the intended app root. If you are in a monorepo wrapper, use the returned app candidates and exact next action. If no live session exists, use the exact Start Dev next action returned by runtime status so occupied router/HMR ports are avoided. Do not `curl` normal page routes to identify a port owner. If a live session exists but runtime/MCP is unreachable, stop the listed session file first, then start dev again.
+7. Use MCP `diagnose { projectId, path }` for the smallest trustworthy runtime surface before broad checks only after runtime health is reachable; use `proteum diagnose <path> --port <port>` as fallback or terminal evidence.
+8. Use MCP `perf_request { projectId, query }` for performance, CPU, SQL, render, cache, or connected-boundary questions; use `proteum perf request <requestId|path>` as fallback or terminal evidence.
+9. Use `proteum trace show <requestId> --events` only when compact diagnose, perf, trace, or MCP output says lower-level event detail is needed.
+10. Use `proteum explain --manifest` or read `./.proteum/manifest.json` only when compact `workflow_start`/`orient`/`explain`/MCP summary cannot answer the specific manifest question.
+11. Use `proteum verify browser` for browser-visible verification, or `proteum e2e --port <port>` for targeted/full Playwright suites. Keep auth sourced from Proteum session helpers.
+12. Run global checks second, not first. Unrelated diagnostics should remain visible but non-blocking during focused verification unless strict global mode is required.
+13. Open the profiler only when a human-readable view helps; it should agree with the CLI and MCP after refresh.

package/docs/mcp.md

@@ -1,37 +1,57 @@
 # Proteum MCP
 
-Proteum exposes read-only MCP surfaces for agents that need repeated, compact access to project and runtime state.
+Proteum exposes MCP through two coordinated surfaces:
 
-There are two entrypoints:
+- `proteum mcp`: one machine-scope router for live Proteum dev projects.
+- `proteum dev`: one app-root runtime endpoint at `http://localhost:<port>/__proteum/mcp`.
 
-- `proteum mcp`: a stdio MCP server launched from an app or worktree.
-- `proteum dev`: a dev-hosted MCP endpoint at `/__proteum/mcp`.
+Agents should normally connect to `proteum mcp`. The router discovers live `proteum dev` sessions from the machine registry, can resolve offline Proteum app roots from a supplied `cwd`, returns stable `projectId` values for live projects, and forwards app-bound reads to the selected dev-hosted endpoint.
 
-Both entrypoints expose the same tool/resource contract. The CLI remains the source of truth for `dev`, `build`, `check`, `refresh`, migrations, and reproducible terminal validation. MCP is for low-token reads, runtime snapshots, trace/perf/log summaries, and progressive detail loading.
+## Machine Router
 
-## Stdio Server
-
-Configure an MCP client to launch the server from the app root:
+Start the router from any directory:
 
 ```bash
 proteum mcp
 ```
 
-Useful options:
+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:
 
 ```bash
-proteum mcp --cwd /path/to/app
-proteum mcp --url http://localhost:3101
-proteum mcp --session-file var/run/proteum/dev/agents/task.json
+proteum mcp --stdio
 ```
 
-The stdio server reads manifest, instruction, and tracked-session data from disk. When a live dev server is known through `--url`, a tracked session file, or the manifest router port, runtime tools read the dev endpoints directly instead of spawning CLI commands.
+`proteum dev` ensures the managed machine MCP daemon is running before the dev loop starts. Only one managed daemon may run at a time. Stale daemon records are cleaned automatically.
+
+The router is read-only. It does not start or stop dev servers, mutate files, refresh generated code, run migrations, or execute commands.
+
+Use this flow:
+
+1. Call MCP `workflow_start` with `cwd` or a known `projectId`.
+2. If the result is ambiguous or returns offline app candidates, call `project_resolve { cwd }`, pick the intended app root, start exactly one `proteum dev` server from that app root when needed, then retry `workflow_start`.
+3. Pass the returned live `projectId` to every follow-up app-bound MCP call.
+4. After an MCP read succeeds, do not run the equivalent CLI command or broad source search for the same state; keep CLI for fallback, validation, and final terminal evidence.
+
+Example tool calls:
+
+```json
+{"tool":"workflow_start","arguments":{"cwd":"/repo/apps/product","task":"read-only runtime health pass","route":"/dashboard"}}
+{"tool":"projects_list","arguments":{}}
+{"tool":"project_resolve","arguments":{"cwd":"/repo/apps/product/client/pages"}}
+{"tool":"workflow_start","arguments":{"projectId":"prj_0123abcd4567","route":"/dashboard"}}
+{"tool":"runtime_status","arguments":{"projectId":"prj_0123abcd4567"}}
+{"tool":"orient","arguments":{"projectId":"prj_0123abcd4567","query":"/dashboard"}}
+{"tool":"route_candidates","arguments":{"projectId":"prj_0123abcd4567","query":"dashboard","limit":8}}
+{"tool":"explain_summary","arguments":{"projectId":"prj_0123abcd4567","query":"/dashboard"}}
+{"tool":"diagnose","arguments":{"projectId":"prj_0123abcd4567","path":"/dashboard"}}
+{"tool":"db_query","arguments":{"projectId":"prj_0123abcd4567","sql":"SELECT id, email FROM User LIMIT 5","limit":5}}
+```
 
-Use stdio MCP when the agent environment can launch a long-lived tool server but does not already have direct access to the running `proteum dev` HTTP transport.
+`workflow_start` is the only app-bound bootstrap tool that may resolve from `cwd` when `projectId` is not known. It may return offline app candidates when no matching dev server is running yet. Other app-bound tools require a live `projectId`; if they omit it, the router returns a compact error that tells the agent to call `projects_list` or `project_resolve`. There is no single-project fallback, because wrong-project reads are worse than an explicit routing retry.
 
 ## Dev Runtime Endpoint
 
-During `proteum dev`, the app exposes the same MCP contract through the official streamable HTTP transport:
+During `proteum dev`, the app exposes the same app-level MCP contract through the official streamable HTTP transport:
 
 ```text
 POST /__proteum/mcp
@@ -39,7 +59,7 @@ GET /__proteum/mcp
 DELETE /__proteum/mcp
 ```
 
-This endpoint is dev-only and local-tooling-only. It uses the running app's in-memory diagnostics, trace, perf, and log stores where possible, so runtime tools avoid process startup and avoid dumping full trace payloads by default.
+This endpoint is dev-only and local-tooling-only. It is already rooted to the running app, so its tools do not require `projectId` or `cwd`. The machine router strips routing fields before forwarding a call here.
 
 The dev session UI and ready banner print:
 
@@ -48,11 +68,30 @@ mcp  http://localhost:<port>/__proteum/mcp
 MCP: http://localhost:<port>/__proteum/mcp
 ```
 
-Use dev-hosted MCP when an agent is iterating against an already running app. It is the fastest path for repeated `runtime_status`, `orient`, `diagnose`, `trace_*`, `perf_*`, and `logs_tail` reads.
+`proteum dev` also writes a machine registry record under `~/.proteum/dev-sessions/`. The stable `projectId` is derived from the canonical app root, so it remains stable across port or session-file changes.
+
+## Discovery And Recovery
+
+If machine MCP routing fails:
+
+1. Run `proteum mcp status`.
+2. Run `proteum runtime status` from the intended app root. If you are in a monorepo wrapper, use the returned app candidates and exact next action instead of starting dev from the wrapper.
+3. If no live app session exists, use the exact Start Dev next action returned by runtime status. It checks the configured router/HMR ports and suggests an alternate free port when the manifest default is occupied.
+4. If a live session exists but runtime/MCP is unreachable, stop the listed session file with `proteum dev stop --session-file <path>`, then start dev again.
+5. Retry MCP `workflow_start` and use the returned `projectId`.
+
+Offline `project_resolve` and `workflow_start` candidates also inspect configured router/HMR ports before returning `nextAction`. If the configured port already serves the same app but no live machine project is registered, the next action is runtime tracking repair, not starting a second dev server.
+
+`proteum runtime status` refreshes the machine registry for live tracked sessions, so this recovery path also repairs missing router records after an upgrade.
+
+Do not start a second `proteum dev` server in the same worktree. `proteum dev` fails fast when another live tracked session already exists for the same app root.
+Do not start a second managed `proteum mcp` daemon. `proteum mcp` reuses the live daemon or reports its current URL.
+Do not call `diagnose`, `trace_*`, or `perf_*` while runtime health is unreachable; repair or start dev first.
+Do not `curl` normal page routes to identify port ownership; use `proteum runtime status` or Proteum dev-only `/__proteum/*` endpoints so wrong-app HTML is never dumped into agent context.
 
 ## Output Contract
 
-MCP tool and resource payloads are compact single-line JSON strings in this shape:
+MCP tool payloads are compact single-line JSON strings in this shape:
 
 ```json
 {"ok":true,"format":"proteum-mcp-v1","summary":"...","data":{},"nextActions":[],"omitted":[]}
@@ -69,13 +108,22 @@ Do not make MCP tools return pretty-printed JSON or raw trace/log dumps by defau
 
 ## Tools
 
-The v1 tools are read-only:
+Machine-only tools:
+
+| Tool | Purpose |
+| --- | --- |
+| `projects_list` | List live Proteum dev projects and stable `projectId` values |
+| `project_resolve` | Resolve a live project or offline app candidate by `projectId`, `cwd`, app root, or app-root substring |
+
+App-bound tools require `projectId` when called through `proteum mcp`:
 
 | Tool | Purpose |
 | --- | --- |
+| `workflow_start` | One-call bootstrap with resolved project, runtime, selected instruction previews, owner summary, doctor summaries, duplicate-avoidance rules, and next actions |
 | `runtime_status` | Manifest summary, selected runtime, tracked sessions, health, and MCP URL |
 | `orient` | Owner, instruction routing, connected boundaries, and next actions |
-| `instructions_resolve` | Selected instruction files for a query, with short previews |
+| `instructions_resolve` | Selected instruction files for a query, with short previews and full-read policy |
+| `route_candidates` | Compact route/controller/page matches for a query without dumping the raw route table |
 | `explain_summary` | Compact manifest summary or owner lookup |
 | `doctor` | Compact manifest and optional contract diagnostics |
 | `diagnose` | Composite diagnosis for an existing route, query, or request trace |
@@ -84,53 +132,47 @@ The v1 tools are read-only:
 | `perf_top` | Hot-path perf rollup |
 | `perf_request` | One-request waterfall and attribution |
 | `logs_tail` | Capped recent server logs |
-
-MCP v1 intentionally does not start/stop dev servers, refresh generated files, arm traces, export traces, write files, run migrations, or execute app commands.
-
-## Resources
-
-Static resources expose common compact reads:
-
-- `proteum://runtime/status`
-- `proteum://instructions/router`
-- `proteum://manifest/summary`
-- `proteum://trace/latest/summary`
-- `proteum://perf/top`
+| `db_query` | Capped read-only database diagnostics for one `SELECT`, `SHOW`, or `EXPLAIN` statement |
 
 ## CLI Boundary
 
 Use CLI commands when the result must be reproducible as a terminal step, CI-like validation, or human-shareable command output:
 
 ```bash
-proteum dev
+proteum dev --session-file var/run/proteum/dev/agents/task.json --port 3101
 proteum build --prod
 proteum check
 proteum refresh
 proteum diagnose /dashboard --port 3101
 proteum verify request /dashboard --port 3101
 proteum trace show <requestId> --events --port 3101
+proteum explain owner /dashboard
+proteum db query "SELECT id, email FROM User LIMIT 5" --port 3101
+proteum explain --routes --controllers --full # only when the raw route/controller arrays are required
 ```
 
-Use MCP when an agent is asking the same running app for repeated state:
+Use MCP when an agent is asking a running app for repeated state:
 
 ```text
-runtime_status
-instructions_resolve
-orient
-diagnose
-trace_latest
-perf_request
-logs_tail
+workflow_start { cwd, task, route? }
+runtime_status { projectId }
+instructions_resolve { projectId, query }
+orient { projectId, query }
+route_candidates { projectId, query }
+explain_summary { projectId, query }
+doctor { projectId }
+diagnose { projectId, path }
+trace_show { projectId, requestId }
+trace_latest { projectId }
+perf_request { projectId, query }
+logs_tail { projectId }
+db_query { projectId, sql, limit? }
 ```
 
-## Routing Guidance
+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.
 
-Use these surfaces in this order:
+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.
 
-1. Agent instructions for hard safety policy and routing rules.
-2. MCP for repeated reads, runtime status, instruction selection, traces, perf, and logs.
-3. Compact CLI for reproducible terminal validation and CI-like checks.
-4. Full CLI escape hatches only after compact MCP/CLI output identifies the missing detail.
 
 ## Benchmark
 
@@ -140,10 +182,32 @@ The Product `/domains` diagnostic loop measured on May 7, 2026 used `ceil(UTF-8
 | --- | ---: | ---: |
 | Compact CLI single loop | 6,286 | 4,809 ms |
 | Dev-hosted HTTP MCP single loop | 5,211 | 232 ms |
-| Stdio MCP single loop | 5,526 | 900 ms |
 | Compact CLI repeated reads x3 | 11,660 | 9,572 ms |
 | Dev-hosted HTTP MCP repeated reads x3 | 10,537 | 214 ms |
 
-The benchmark included the routed instruction docs separately. Reading the four selected instruction files once was about 4,881 estimated output tokens; refreshing the instruction routing through MCP `instructions_resolve` was about 722 estimated output tokens.
+Machine routing adds one lightweight `projects_list` lookup but keeps repeated app reads on the dev-hosted runtime endpoint. The practical rule is: use CLI for reproducible checks and final evidence, then use MCP with `projectId` for repeated reads against the same app/runtime.
+
+## Codex Usage Test
+
+Proteum core uses Vitest for framework tests. The live Codex MCP usage test is opt-in because it runs the real Codex CLI, may spend model tokens, and depends on the developer machine's Codex auth plus MCP registration.
 
-The practical rule from the benchmark is: use CLI for the first reproducible check and validation record, then use MCP for repeated reads against the same app/runtime.
+```bash
+PROTEUM_CODEX_MCP_USAGE_CWD=/absolute/path/to/proteum/app npm run test:codex-mcp
+```
+
+The test sends a read-only runtime health prompt to `codex exec --json`, stores the JSONL transcript, stderr, last message, and `summary.json`, then asserts:
+
+- token usage was reported and quantified
+- at least one Proteum MCP `workflow_start` call happened
+- total Proteum MCP calls meet `PROTEUM_CODEX_MCP_MIN_MCP_CALLS` (`4` by default)
+- Proteum CLI fallback calls stay under `PROTEUM_CODEX_MCP_MAX_CLI_CALLS` (`4` by default)
+
+Useful optional variables:
+
+```bash
+CODEX_CLI=/path/to/codex
+PROTEUM_CODEX_MCP_USAGE_OUTPUT_DIR=/tmp/proteum-codex-mcp-usage
+PROTEUM_CODEX_MCP_USAGE_TIMEOUT_MS=1200000
+PROTEUM_CODEX_MCP_MIN_MCP_CALLS=4
+PROTEUM_CODEX_MCP_MAX_CLI_CALLS=4
+```