proteum 2.2.9 → 2.4.1

package/common/dev/mcpServer.ts

@@ -0,0 +1,287 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CallToolResult, ReadResourceResult } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod/v4';
+
+import { stringifyMcpPayload, type TProteumMcpPayload } from './mcpPayloads';
+
+export type TProteumMcpDetail = 'compact' | 'full';
+
+export type TProteumMcpProvider = {
+    diagnose: (input: {
+        logsLevel?: 'silly' | 'log' | 'info' | 'warn' | 'error';
+        logsLimit?: number;
+        path?: string;
+        query?: string;
+        requestId?: string;
+    }) => Promise<TProteumMcpPayload>;
+    doctor: (input: { contracts?: boolean }) => Promise<TProteumMcpPayload>;
+    explainSummary: (input: { query?: string }) => Promise<TProteumMcpPayload>;
+    instructionsResolve: (input: { query?: string }) => Promise<TProteumMcpPayload>;
+    logsTail: (input: { level?: 'silly' | 'log' | 'info' | 'warn' | 'error'; limit?: number }) => Promise<TProteumMcpPayload>;
+    orient: (input: { query: string }) => Promise<TProteumMcpPayload>;
+    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 = {
+    provider: TProteumMcpProvider;
+    version: string;
+};
+
+const jsonToolResult = (payload: object): CallToolResult => ({
+    content: [
+        {
+            type: 'text',
+            text: stringifyMcpPayload(payload),
+        },
+    ],
+});
+
+const jsonResourceResult = (uri: string, payload: object): ReadResourceResult => ({
+    contents: [
+        {
+            mimeType: 'application/json',
+            text: stringifyMcpPayload(payload),
+            uri,
+        },
+    ],
+});
+
+const readOnlyAnnotations = {
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+    readOnlyHint: true,
+};
+
+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();
+
+export const createProteumMcpServer = ({ provider, version }: TCreateProteumMcpServerArgs) => {
+    const server = new McpServer(
+        {
+            name: 'proteum',
+            version,
+        },
+        {
+            capabilities: {
+                logging: {},
+            },
+        },
+    );
+
+    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',
+        {
+            annotations: readOnlyAnnotations,
+            description: 'Return the compact Proteum app manifest, selected dev runtime, tracked sessions, and health.',
+            inputSchema: {},
+            title: 'Proteum Runtime Status',
+        },
+        async () => jsonToolResult(await provider.runtimeStatus({})),
+    );
+
+    server.registerTool(
+        'orient',
+        {
+            annotations: readOnlyAnnotations,
+            description: 'Resolve owners, instruction files, connected boundaries, and next diagnostic actions for a query.',
+            inputSchema: {
+                query: z.string().min(1).describe('Route, controller, file path, connected namespace, or task query.'),
+            },
+            title: 'Proteum Orient',
+        },
+        async ({ query }) => jsonToolResult(await provider.orient({ query })),
+    );
+
+    server.registerTool(
+        'instructions_resolve',
+        {
+            annotations: readOnlyAnnotations,
+            description: 'Return the routed Proteum instruction files an agent should read for the current query.',
+            inputSchema: {
+                query: z.string().optional().describe('Optional task, route, file path, or area query.'),
+            },
+            title: 'Proteum Instruction Routing',
+        },
+        async ({ query }) => jsonToolResult(await provider.instructionsResolve({ query })),
+    );
+
+    server.registerTool(
+        'explain_summary',
+        {
+            annotations: readOnlyAnnotations,
+            description: 'Return a compact manifest summary or owner ranking without dumping the full generated manifest.',
+            inputSchema: {
+                query: z.string().optional().describe('Optional owner query. Omit for the manifest summary.'),
+            },
+            title: 'Proteum Explain Summary',
+        },
+        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',
+        {
+            annotations: readOnlyAnnotations,
+            description: 'Return compact manifest diagnostics, optionally including generated-contract diagnostics.',
+            inputSchema: {
+                contracts: z.boolean().optional().describe('Include generated contract diagnostics.'),
+            },
+            title: 'Proteum Doctor',
+        },
+        async ({ contracts }) => jsonToolResult(await provider.doctor({ contracts })),
+    );
+
+    server.registerTool(
+        'diagnose',
+        {
+            annotations: readOnlyAnnotations,
+            description: 'Read the dev runtime composite diagnosis for an existing trace, route, request id, or query.',
+            inputSchema: {
+                logsLevel: logsLevelSchema,
+                logsLimit: z.number().int().min(0).max(100).optional(),
+                path: z.string().optional(),
+                query: z.string().optional(),
+                requestId: z.string().optional(),
+            },
+            title: 'Proteum Diagnose',
+        },
+        async ({ logsLevel, logsLimit, path, query, requestId }) =>
+            jsonToolResult(await provider.diagnose({ logsLevel, logsLimit, path, query, requestId })),
+    );
+
+    server.registerTool(
+        'trace_latest',
+        {
+            annotations: readOnlyAnnotations,
+            description: 'Return a compact summary of the latest request trace, with optional paginated full detail.',
+            inputSchema: {
+                detail: detailSchema,
+                limit: positiveLimitSchema,
+                offset: offsetSchema,
+            },
+            title: 'Proteum Latest Trace',
+        },
+        async ({ detail, limit, offset }) => jsonToolResult(await provider.traceLatest({ detail, limit, offset })),
+    );
+
+    server.registerTool(
+        'trace_show',
+        {
+            annotations: readOnlyAnnotations,
+            description: 'Return a compact or paginated full summary of a specific request trace.',
+            inputSchema: {
+                detail: detailSchema,
+                limit: positiveLimitSchema,
+                offset: offsetSchema,
+                requestId: z.string().min(1),
+            },
+            title: 'Proteum Trace Show',
+        },
+        async ({ detail, limit, offset, requestId }) =>
+            jsonToolResult(await provider.traceShow({ detail, limit, offset, requestId })),
+    );
+
+    server.registerTool(
+        'perf_top',
+        {
+            annotations: readOnlyAnnotations,
+            description: 'Return compact trace-derived performance rollups for hot routes, paths, or controllers.',
+            inputSchema: {
+                groupBy: z.enum(['path', 'route', 'controller']).optional(),
+                limit: z.number().int().min(1).max(50).optional(),
+                since: z.string().optional(),
+            },
+            title: 'Proteum Perf Top',
+        },
+        async ({ groupBy, limit, since }) => jsonToolResult(await provider.perfTop({ groupBy, limit, since })),
+    );
+
+    server.registerTool(
+        'perf_request',
+        {
+            annotations: readOnlyAnnotations,
+            description: 'Return a compact waterfall and attribution summary for one traced request id or path.',
+            inputSchema: {
+                query: z.string().min(1).describe('Request id or path.'),
+            },
+            title: 'Proteum Perf Request',
+        },
+        async ({ query }) => jsonToolResult(await provider.perfRequest({ query })),
+    );
+
+    server.registerTool(
+        'logs_tail',
+        {
+            annotations: readOnlyAnnotations,
+            description: 'Return capped recent Proteum dev server logs.',
+            inputSchema: {
+                level: logsLevelSchema,
+                limit: z.number().int().min(0).max(100).optional(),
+            },
+            title: 'Proteum Logs Tail',
+        },
+        async ({ level, limit }) => jsonToolResult(await provider.logsTail({ level, limit })),
+    );
+
+    for (const [name, uri, description] of [
+        ['runtime-status', 'proteum://runtime/status', 'Current compact runtime status.'],
+        ['instructions-router', 'proteum://instructions/router', 'Current instruction routing contract.'],
+        ['manifest-summary', 'proteum://manifest/summary', 'Compact generated manifest summary.'],
+        ['trace-latest-summary', 'proteum://trace/latest/summary', 'Latest request trace summary.'],
+        ['perf-top', 'proteum://perf/top', 'Current compact perf top rollup.'],
+    ] as const) {
+        server.registerResource(
+            name,
+            uri,
+            {
+                description,
+                mimeType: 'application/json',
+                title: description,
+            },
+            async (resourceUri) => jsonResourceResult(resourceUri.href, await provider.readResource(uri)),
+        );
+    }
+
+    return server;
+};

package/docs/agent-routing.md

@@ -0,0 +1,137 @@
+# Agent Routing And Token Efficiency
+
+Proteum routing and diagnostics CLI commands are agent-facing by default. The interactive `proteum dev` and user-facing `proteum build` surfaces keep their human presentation.
+
+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, routed by `projectId`
+
+The routing strategy is:
+
+1. Use instructions for hard safety rules and routing only.
+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
+
+Past agent workflows spent too much context on repeated instruction payloads, full manifest dumps, raw trace JSON, and broad source searches.
+
+The measured Product diagnostic loop produced roughly tens of thousands of output tokens because agents combined:
+
+- `dev list`
+- `orient`
+- full `diagnose`
+- raw `trace latest`
+- `perf request`
+- `verify request`
+- 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.
+
+## CLI Contract
+
+Default CLI output for agent commands is compact `proteum-agent-v1` JSON:
+
+```json
+{
+  "ok": true,
+  "format": "proteum-agent-v1",
+  "summary": "...",
+  "data": {},
+  "nextActions": [],
+  "omitted": [],
+  "fullDetailCommand": "..."
+}
+```
+
+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>
+proteum runtime status
+proteum diagnose <target>
+proteum perf request <requestId|path>
+proteum trace latest
+```
+
+Use MCP for repeated reads when a client is available:
+
+```text
+proteum mcp
+```
+
+The machine router discovers live `proteum dev` sessions and offline Proteum app roots under a cwd. `proteum dev` ensures one managed machine MCP daemon is running; terminal `proteum mcp` starts or reuses that daemon, while MCP clients can use stdio. Agents should call MCP `workflow_start` with `cwd` or a known `projectId`, use `project_resolve { cwd }` when routing is ambiguous or offline, and pass the returned live `projectId` to every follow-up app-bound MCP tool. Offline candidates include port-inspected next actions, so agents should follow those instead of guessing the manifest default port. The router forwards to the selected dev-hosted `/__proteum/mcp` endpoint and strips routing fields before the app sees the call.
+
+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 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.
+
+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
+proteum perf request <requestId> --full
+```
+
+## Instruction Contract
+
+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
+- `client/AGENTS.md`: client code
+- `client/pages/AGENTS.md`: page route/data/render rules
+- `server/services/AGENTS.md`: services
+- `server/routes/AGENTS.md`: manual routes
+- `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 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.
+
+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
+
+The latest Product `/domains` benchmark used routed instructions plus the compact CLI/MCP stack. Token estimates are `ceil(UTF-8 bytes / 4)` and measure output size only.
+
+| Workflow | Approx output tokens | Elapsed |
+| --- | ---: | ---: |
+| Compact CLI single loop | 6,286 | 4,809 ms |
+| Dev-hosted HTTP MCP single loop | 5,211 | 232 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 `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,6 +79,8 @@ 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 with the selected `projectId` for repeated diagnostics, trace, perf, status, and log reads, not for running commands.
+
 ### HTTP Endpoints
 
 The CLI remote mode and the profiler use the same dev-only endpoints:

package/docs/dev-sessions.md

@@ -78,13 +78,14 @@ 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, then use `proteum trace` 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:
 
 ```bash
 proteum orient /dashboard
+proteum runtime status
 proteum session admin@example.com --role ADMIN --port 3101 --json > session.json
 proteum e2e --port 3101 --session-email admin@example.com --session-role ADMIN tests/e2e/features/dashboard.spec.ts
 proteum diagnose /dashboard --hit /dashboard --port 3101
@@ -92,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

@@ -11,21 +11,26 @@ These are not separate models for different tools. `orient`, `explain`, and `doc
 
 Performance inspection is a sibling surface, not a separate instrumentation stack: `proteum perf` and the profiler `Perf` tab aggregate the same dev-only request traces that back `proteum trace`.
 
+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 `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
 
 The canonical snapshot lives in `./.proteum/manifest.json`.
 
-Proteum uses that same manifest in seven places:
+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
 - the `Explain`, `Doctor`, and `Diagnose` tabs in the bottom profiler during `proteum dev`
 
-This means the CLI, the dev HTTP endpoints, and the profiler all describe the same framework-owned snapshot before any live trace or log overlays are added.
+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.
 
 If a command such as `proteum explain`, `proteum doctor`, `proteum diagnose`, or `proteum refresh` regenerates `.proteum/manifest.json`, the next CLI call, HTTP call, or profiler refresh will reflect that same updated snapshot.
 
@@ -39,11 +44,12 @@ proteum orient /api/Auth/CurrentUser
 proteum explain
 proteum explain owner /api/Auth/CurrentUser
 proteum explain --routes --controllers --commands
-proteum explain --all --json
+proteum explain --routes --controllers --commands --full
+proteum explain --manifest
 
 proteum doctor
 proteum doctor --contracts
-proteum doctor --json
+proteum doctor --full
 proteum doctor --strict
 
 proteum diagnose /
@@ -59,45 +65,76 @@ proteum perf top --since today
 proteum perf request /dashboard --port 3101
 proteum perf compare --baseline yesterday --target today --group-by route
 proteum perf memory --since 1h --group-by controller
+
+proteum runtime status
+```
+
+Default compact command output follows this shape:
+
+```json
+{
+  "ok": true,
+  "format": "proteum-agent-v1",
+  "summary": "...",
+  "data": {},
+  "nextActions": [],
+  "omitted": [],
+  "fullDetailCommand": "..."
+}
 ```
 
-`proteum orient --json` emits:
+`proteum orient` emits compact agent JSON with:
 
 - `query`
-- `normalizedQuery`
 - `app`
-- `guidance`
 - `owner`
+- `instructions.mustRead`
+- `instructions.readWhen`
 - `connected`
-- `nextSteps`
+- `nextActions`
 - `warnings`
 
-`proteum explain --json` emits the selected manifest sections as machine-readable JSON.
+`proteum orient --full` emits the full orientation payload.
+
+`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> --json` keeps the existing owner ranking shape and adds:
+`proteum explain owner <query>` emits compact owner ranking. `proteum explain owner <query> --full` keeps the existing full owner ranking shape and adds:
 
 - `scopeLabel`
 - `originHint`
 
-`proteum doctor --json` emits:
+`proteum doctor` emits compact diagnostics. `proteum doctor --full` emits:
 
 - `summary.errors`
 - `summary.warnings`
 - `summary.strictFailed`
 - `diagnostics`
 
-`proteum diagnose` emits a composite response with:
+`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.
+
+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:
+
+```json
+{"ok":true,"format":"proteum-mcp-v1","summary":"...","data":{},"nextActions":[],"omitted":[]}
+```
+
+Use MCP for repeated reads of the same app/runtime state. Keep CLI commands for reproducible validation, final evidence, and CI-like command output.
+
+`proteum diagnose` emits a compact composite response with:
 
 - `owner`
-- `orientation`
+- `instructions`
 - `chain`
 - `doctor`
 - `contracts`
 - `request`
-- `attribution`
 - `suspects`
 - `serverLogs`
 
+`proteum diagnose --full` emits the full lower-level composite response, including raw request trace payloads.
+
 `proteum verify owner|request|browser --json` emits:
 
 - `action`
@@ -115,6 +152,8 @@ proteum perf memory --since 1h --group-by controller
 - `compare`: grouped baseline vs target deltas
 - `memory`: grouped heap and RSS drift summaries
 
+`proteum trace latest` and `proteum trace show <requestId>` emit compact trace summaries by default. Use `--events` or `--full` to print the raw event stream, payload summaries, and SQL text.
+
 Focused verification defaults to the smallest trustworthy surface first:
 
 - `verify owner`: orient the target, then choose request, command, or local owner-scoped diagnostics
@@ -137,6 +176,7 @@ In `profile: dev`, the running app exposes:
 - `GET /__proteum/perf/compare`
 - `GET /__proteum/perf/memory`
 - `GET /__proteum/perf/request`
+- `POST|GET|DELETE /__proteum/mcp`
 
 `/__proteum/explain` supports optional section selection:
 
@@ -169,6 +209,8 @@ 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 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
 
 During `proteum dev`, the bottom profiler is the human-facing UI over the same dev diagnostics surfaces.
@@ -207,12 +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>` when the target might be generated, connected, framework-owned, or multi-repo.
-2. Read `./.proteum/manifest.json` or run `proteum explain --json` only after you know which surface matters.
-3. Run `proteum doctor --json` and `proteum doctor --contracts --json` to inspect framework and generated-artifact diagnostics.
-4. Use `proteum verify owner <query>` or `proteum diagnose <path> --port <port>` for the smallest trustworthy runtime surface before broad checks.
-5. Use `proteum verify browser` for browser-visible verification, or `proteum e2e --port <port>` for targeted/full Playwright suites. Only drop to direct Playwright when the Proteum wrapper cannot express the needed control. Keep auth sourced from Proteum session helpers, and reserve browser flows for the final verifier agent unless they are the only trustworthy surface.
-6. For performance, CPU, SQL, render, cache, or connected-boundary questions, use `proteum perf request <requestId|path>` against the same running dev server.
-7. Use `proteum trace ...` when you need lower-level event detail than `diagnose` or `perf` provides.
-8. Run global checks second, not first. Unrelated diagnostics should remain visible but non-blocking during focused verification unless strict global mode is required.
-9. Open the profiler only when a human-readable view helps; it should agree with the CLI 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.