proteum 2.2.9 → 2.3.0

package/common/dev/mcpServer.ts

@@ -0,0 +1,254 @@
+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>;
+    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>;
+};
+
+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(
+        '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(
+        '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,126 @@
+# 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
+
+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.
+
+## 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 `explain --json`
+
+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 the compact commands first:
+
+```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:
+
+```bash
+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:
+
+```text
+http://localhost:<port>/__proteum/mcp
+```
+
+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.
+
+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 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.
+
+Area files carry only their own source content:
+
+- `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 read only `mustRead` from `orient`, plus conditional docs that match the current task.
+
+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.
+
+## 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 |
+| 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

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 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` 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

package/docs/diagnostics.md

@@ -11,11 +11,15 @@ 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 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).
+
 ## 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
@@ -23,9 +27,10 @@ Proteum uses that same manifest in seven places:
 - `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 `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,11 @@ proteum orient /api/Auth/CurrentUser
 proteum explain
 proteum explain owner /api/Auth/CurrentUser
 proteum explain --routes --controllers --commands
-proteum explain --all --json
+proteum explain --manifest
 
 proteum doctor
 proteum doctor --contracts
-proteum doctor --json
+proteum doctor --full
 proteum doctor --strict
 
 proteum diagnose /
@@ -59,45 +64,79 @@ 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
+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:
+
+```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. `proteum explain --manifest` emits the full generated manifest, and explicit section flags such as `--routes --controllers` emit those sections.
 
-`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, health status, and a suggested next command. Use it before starting another dev 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.
+
+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 +154,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 +178,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 +211,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 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.
+
 ## Profiler
 
 During `proteum dev`, the bottom profiler is the human-facing UI over the same dev diagnostics surfaces.
@@ -207,12 +251,13 @@ 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. 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.