proteum 2.5.4 → 2.5.6

package/cli/runtime/worktreeBootstrap.ts

@@ -2,6 +2,7 @@ import cp from 'child_process';
 import crypto from 'crypto';
 import fs from 'fs-extra';
 import path from 'path';
+import { findProteumAppRootsUnder } from '../utils/appRoots';
 
 /*----------------------------------
 - TYPES
@@ -124,6 +125,30 @@ export type TRunWorktreeBootstrapCreateOptions = TRunWorktreeBootstrapInitOption
     targetRepoRoot: string;
 };
 
+export type TMonorepoWorktreeBootstrapAppResult = {
+    appRoot: string;
+    error?: string;
+    markerFilepath?: string;
+    ok: boolean;
+    refresh?: string;
+    relativeAppRoot: string;
+    runtimeStatus?: string;
+    sourceAppRoot?: string;
+    status?: TWorktreeBootstrapStatus;
+};
+
+export type TRunMonorepoWorktreeBootstrapInitOptions = Omit<TRunWorktreeBootstrapInitOptions, 'appRoot' | 'source'> & {
+    appRoots?: string[];
+    monorepoRoot: string;
+    source?: string;
+};
+
+export type TRunMonorepoWorktreeBootstrapCreateOptions = TRunMonorepoWorktreeBootstrapInitOptions & {
+    base?: string;
+    branch: string;
+    targetRepoRoot: string;
+};
+
 /*----------------------------------
 - CONSTANTS
 ----------------------------------*/
@@ -139,6 +164,16 @@ const codexWorktreeSegment = `${path.sep}.codex${path.sep}worktrees${path.sep}`;
 
 const normalizePath = (value: string) => path.normalize(path.resolve(value));
 
+const normalizeExistingPath = (value: string) => {
+    const normalized = normalizePath(value);
+
+    try {
+        return path.normalize(fs.realpathSync(normalized));
+    } catch {
+        return normalized;
+    }
+};
+
 const isTruthyEnv = (value: string | undefined) => value === '1' || value === 'true' || value === 'yes';
 
 const nowIso = () => new Date().toISOString();
@@ -699,3 +734,131 @@ export const runWorktreeBootstrapCreate = async ({
         worktreeBootstrap: initResult,
     };
 };
+
+const findBootstrapInstallRoot = (appRoot: string) => {
+    const packageLockFilepath = findNearestExistingPath(appRoot, 'package-lock.json');
+    return packageLockFilepath ? path.dirname(packageLockFilepath) : normalizePath(appRoot);
+};
+
+const createSharedDependencyRunner = (runDependencies: (appRoot: string) => Promise<void> = runNpmInstall) => {
+    const completedInstallRoots = new Set<string>();
+
+    return async (appRoot: string) => {
+        const installRoot = findBootstrapInstallRoot(appRoot);
+        if (completedInstallRoots.has(installRoot)) return;
+
+        completedInstallRoots.add(installRoot);
+        await runDependencies(installRoot);
+    };
+};
+
+const resolveSourceAppRoot = ({
+    relativeAppRoot,
+    sourceRoot,
+}: {
+    relativeAppRoot: string;
+    sourceRoot?: string;
+}) => {
+    if (!sourceRoot) return undefined;
+
+    const normalizedSourceRoot = normalizeExistingPath(sourceRoot);
+    const sourceAppRoot = path.join(normalizedSourceRoot, relativeAppRoot);
+
+    if (fs.existsSync(sourceAppRoot)) return sourceAppRoot;
+
+    return undefined;
+};
+
+export const runMonorepoWorktreeBootstrapInit = async ({
+    appRoots,
+    monorepoRoot,
+    runDependencies,
+    source,
+    ...initOptions
+}: TRunMonorepoWorktreeBootstrapInitOptions) => {
+    const normalizedMonorepoRoot = normalizeExistingPath(monorepoRoot);
+    const targetAppRoots = (appRoots || findProteumAppRootsUnder(normalizedMonorepoRoot))
+        .map((appRoot) => normalizeExistingPath(appRoot))
+        .sort((left, right) => left.localeCompare(right));
+    const sharedDependencyRunner = createSharedDependencyRunner(runDependencies);
+    const apps: TMonorepoWorktreeBootstrapAppResult[] = [];
+
+    if (targetAppRoots.length === 0) throw new Error(`No Proteum app roots were found under ${normalizedMonorepoRoot}.`);
+
+    for (const appRoot of targetAppRoots) {
+        const relativeAppRoot = path.relative(normalizedMonorepoRoot, appRoot) || '.';
+        const sourceAppRoot = resolveSourceAppRoot({
+            relativeAppRoot,
+            sourceRoot: source,
+        });
+
+        try {
+            const result = await runWorktreeBootstrapInit({
+                ...initOptions,
+                appRoot,
+                runDependencies: sharedDependencyRunner,
+                source: sourceAppRoot,
+            });
+
+            apps.push({
+                appRoot,
+                markerFilepath: result.markerFilepath,
+                ok: true,
+                refresh: result.refresh,
+                relativeAppRoot,
+                runtimeStatus: result.runtimeStatus,
+                sourceAppRoot,
+                status: result.status,
+            });
+        } catch (error) {
+            apps.push({
+                appRoot,
+                error: error instanceof Error ? error.message : String(error),
+                ok: false,
+                relativeAppRoot,
+                sourceAppRoot,
+            });
+        }
+    }
+
+    return {
+        appRoots: targetAppRoots,
+        apps,
+        failed: apps.filter((entry) => !entry.ok).length,
+        monorepoRoot: normalizedMonorepoRoot,
+        ok: apps.every((entry) => entry.ok),
+        sourceRoot: source ? normalizeExistingPath(source) : undefined,
+    };
+};
+
+export const runMonorepoWorktreeBootstrapCreate = async ({
+    base = 'HEAD',
+    branch,
+    source,
+    targetRepoRoot,
+    ...initOptions
+}: TRunMonorepoWorktreeBootstrapCreateOptions) => {
+    if (!branch.trim()) throw new Error('worktree create requires --branch <branch>.');
+    if (!targetRepoRoot.trim()) throw new Error('worktree create requires <target-repo-root>.');
+
+    const normalizedSourceRoot = normalizeExistingPath(source || initOptions.monorepoRoot);
+    const normalizedTargetRepoRoot = path.resolve(targetRepoRoot);
+    const sourceRepoRoot = await findGitRepoRoot(normalizedSourceRoot);
+
+    await runCapture('git', ['worktree', 'add', '-b', branch, normalizedTargetRepoRoot, base], { cwd: sourceRepoRoot });
+
+    const initResult = await runMonorepoWorktreeBootstrapInit({
+        ...initOptions,
+        monorepoRoot: normalizedTargetRepoRoot,
+        refresh: true,
+        source: normalizedSourceRoot,
+    });
+
+    return {
+        branch,
+        sourceMonorepoRoot: normalizedSourceRoot,
+        sourceRepoRoot,
+        targetRepoRoot: normalizedTargetRepoRoot,
+        worktreeBootstrap: initResult,
+    };
+};

package/cli/utils/agents.ts

@@ -12,14 +12,30 @@ import { createStartDevCommand, findProteumAppRootsUnder, readProteumAppRootSumm
 - TYPES
 ----------------------------------*/
 
-type TProjectInstructionArgs = { appRoot?: string; coreRoot: string; includeMonorepoRegistry?: boolean; monorepoRoot?: string };
+type TProjectInstructionArgs = {
+    appRoot?: string;
+    coreRoot: string;
+    includeMonorepoRegistry?: boolean;
+    monorepoRegistryCurrentAppRoot?: string;
+    monorepoRoot?: string;
+};
 type TConfigureProjectAgentInstructionsArgs = {
     appRoot: string;
     coreRoot: string;
     dryRun?: boolean;
+    includeAppInstructions?: boolean;
+    includeRootInstructions?: boolean;
+    markCurrentAppInMonorepoRegistry?: boolean;
     monorepoRoot?: string;
     overwriteBlockedPaths?: string[];
 };
+type TConfigureMonorepoProjectAgentInstructionsArgs = {
+    appRoots: string[];
+    coreRoot: string;
+    dryRun?: boolean;
+    monorepoRoot: string;
+    overwriteBlockedPaths?: string[];
+};
 
 type TAgentInstructionDefinition = {
     projectPath: string;
@@ -49,6 +65,12 @@ export type TConfigureProjectAgentInstructionsResult = {
     updatedGitignores: string[];
 };
 
+export type TConfigureMonorepoProjectAgentInstructionsResult = Omit<TConfigureProjectAgentInstructionsResult, 'appRoot'> & {
+    appRoots: string[];
+    monorepoRoot: string;
+    mode: 'monorepo';
+};
+
 /*----------------------------------
 - CONSTANTS
 ----------------------------------*/
@@ -115,6 +137,9 @@ export function configureProjectAgentInstructions({
     appRoot,
     coreRoot,
     dryRun = false,
+    includeAppInstructions = true,
+    includeRootInstructions = true,
+    markCurrentAppInMonorepoRegistry = true,
     monorepoRoot,
     overwriteBlockedPaths = [],
 }: TConfigureProjectAgentInstructionsArgs): TConfigureProjectAgentInstructionsResult {
@@ -147,11 +172,12 @@ export function configureProjectAgentInstructions({
                   appRoot: normalizedAppRoot,
                   coreRoot,
                   includeMonorepoRegistry: true,
+                  monorepoRegistryCurrentAppRoot: markCurrentAppInMonorepoRegistry ? normalizedAppRoot : undefined,
                   monorepoRoot: normalizedMonorepoRoot,
               })
             : appEmbeddedInstructions;
 
-    if (mode === 'monorepo' && normalizedMonorepoRoot) {
+    if (includeRootInstructions && mode === 'monorepo' && normalizedMonorepoRoot) {
         result.monorepoRoot = normalizedMonorepoRoot;
 
         const rootInstructions = getRootAgentInstructionDefinitions();
@@ -172,52 +198,127 @@ export function configureProjectAgentInstructions({
             result.updatedGitignores.push(path.join(normalizedMonorepoRoot, '.gitignore'));
     }
 
-    const appInstructions = getAppAgentInstructionDefinitions({ mode });
-    const appFiles = ensureInstructionFiles(
-        normalizedAppRoot,
-        appInstructions,
-        '[agents]',
-        path.join(coreRoot, 'agents', 'project'),
-        appEmbeddedInstructions,
-        {
-            dryRun,
-            overwriteBlockedPaths: normalizedOverwriteBlockedPaths,
-        },
-    );
-    mergeInstructionResults(result, appFiles, normalizedAppRoot);
-
-    if (mode === 'monorepo') {
-        const retiredAppRootFiles = removeManagedInstructionFiles(
+    if (includeAppInstructions) {
+        const appInstructions = getAppAgentInstructionDefinitions({ mode });
+        const appFiles = ensureInstructionFiles(
             normalizedAppRoot,
-            [...sharedRootDocumentInstructionDefinitions, ...sharedTestAgentInstructionDefinitions],
+            appInstructions,
             '[agents]',
             path.join(coreRoot, 'agents', 'project'),
+            appEmbeddedInstructions,
             {
                 dryRun,
+                overwriteBlockedPaths: normalizedOverwriteBlockedPaths,
             },
         );
-        mergeInstructionResults(result, retiredAppRootFiles, normalizedAppRoot);
-    }
+        mergeInstructionResults(result, appFiles, normalizedAppRoot);
+
+        if (mode === 'monorepo') {
+            const retiredAppRootFiles = removeManagedInstructionFiles(
+                normalizedAppRoot,
+                [...sharedRootDocumentInstructionDefinitions, ...sharedTestAgentInstructionDefinitions],
+                '[agents]',
+                path.join(coreRoot, 'agents', 'project'),
+                {
+                    dryRun,
+                },
+            );
+            mergeInstructionResults(result, retiredAppRootFiles, normalizedAppRoot);
+        }
 
-    const appGitignoreCleanupInstructions =
-        mode === 'monorepo'
-            ? [...appInstructions, ...sharedRootDocumentInstructionDefinitions, ...sharedTestAgentInstructionDefinitions]
-            : appInstructions;
-
-    if (
-        !dryRun &&
-        removeInstructionGitignoreEntries({
-            rootDir: normalizedAppRoot,
-            instructionDefinitions: appGitignoreCleanupInstructions,
-        })
-    )
-        result.updatedGitignores.push(path.join(normalizedAppRoot, '.gitignore'));
+        const appGitignoreCleanupInstructions =
+            mode === 'monorepo'
+                ? [...appInstructions, ...sharedRootDocumentInstructionDefinitions, ...sharedTestAgentInstructionDefinitions]
+                : appInstructions;
+
+        if (
+            !dryRun &&
+            removeInstructionGitignoreEntries({
+                rootDir: normalizedAppRoot,
+                instructionDefinitions: appGitignoreCleanupInstructions,
+            })
+        )
+            result.updatedGitignores.push(path.join(normalizedAppRoot, '.gitignore'));
+    }
 
     return result;
 }
 
 export const configureProjectAgentSymlinks = configureProjectAgentInstructions;
 
+export function configureMonorepoProjectAgentInstructions({
+    appRoots,
+    coreRoot,
+    dryRun = false,
+    monorepoRoot,
+    overwriteBlockedPaths = [],
+}: TConfigureMonorepoProjectAgentInstructionsArgs): TConfigureMonorepoProjectAgentInstructionsResult {
+    const normalizedMonorepoRoot = path.resolve(monorepoRoot);
+    const normalizedAppRoots = [...new Set(appRoots.map((appRoot) => path.resolve(appRoot)))].sort((left, right) =>
+        left.localeCompare(right),
+    );
+    const [firstAppRoot] = normalizedAppRoots;
+
+    if (!firstAppRoot) throw new Error('No Proteum app roots were found under the monorepo root.');
+
+    const result: TConfigureMonorepoProjectAgentInstructionsResult = {
+        appRoots: normalizedAppRoots,
+        blocked: [],
+        created: [],
+        mode: 'monorepo',
+        monorepoRoot: normalizedMonorepoRoot,
+        overwritten: [],
+        removed: [],
+        skipped: [],
+        updated: [],
+        updatedGitignores: [],
+    };
+    const mergeProjectResult = (next: TConfigureProjectAgentInstructionsResult) => {
+        result.blocked = [...new Set([...result.blocked, ...next.blocked])];
+        result.created = [...new Set([...result.created, ...next.created])];
+        result.overwritten = [...new Set([...result.overwritten, ...next.overwritten])];
+        result.removed = [...new Set([...result.removed, ...next.removed])];
+        result.skipped = [...new Set([...result.skipped, ...next.skipped])];
+        result.updated = [...new Set([...result.updated, ...next.updated])];
+        result.updatedGitignores = [...new Set([...result.updatedGitignores, ...next.updatedGitignores])];
+    };
+
+    mergeProjectResult(
+        configureProjectAgentInstructions({
+            appRoot: firstAppRoot,
+            coreRoot,
+            dryRun,
+            includeAppInstructions: false,
+            markCurrentAppInMonorepoRegistry: false,
+            monorepoRoot: normalizedMonorepoRoot,
+            overwriteBlockedPaths,
+        }),
+    );
+
+    for (const appRoot of normalizedAppRoots) {
+        mergeProjectResult(
+            configureProjectAgentInstructions({
+                appRoot,
+                coreRoot,
+                dryRun,
+                includeRootInstructions: false,
+                monorepoRoot: normalizedMonorepoRoot,
+                overwriteBlockedPaths,
+            }),
+        );
+    }
+
+    result.blocked = [...new Set(result.blocked)];
+    result.created = [...new Set(result.created)];
+    result.overwritten = [...new Set(result.overwritten)];
+    result.removed = [...new Set(result.removed)];
+    result.skipped = [...new Set(result.skipped)];
+    result.updated = [...new Set(result.updated)];
+    result.updatedGitignores = [...new Set(result.updatedGitignores)];
+
+    return result;
+}
+
 export function resolveProjectAgentMonorepoRoot(appRoot: string) {
     const normalizedAppRoot = resolveCanonicalPath(appRoot);
     const likelyRepoRoot = findLikelyRepoRoot(normalizedAppRoot);
@@ -831,9 +932,11 @@ function renderSingleProjectInstruction({
 
 function renderMonorepoAppRegistry({
     appRoot,
+    currentAppRoot,
     monorepoRoot,
 }: {
     appRoot?: string;
+    currentAppRoot?: string;
     monorepoRoot?: string;
 }) {
     if (!monorepoRoot || !appRoot || path.resolve(monorepoRoot) === path.resolve(appRoot)) return [];
@@ -846,10 +949,13 @@ function renderMonorepoAppRegistry({
     return [
         '## Known Proteum Apps',
         '',
-        'This is a monorepo root wrapper. Do not start `npx proteum dev` from this root; start it from one app root below.',
+        'This is a monorepo root wrapper. Eligible Proteum commands run across the apps below from this root; use an app root when you need to target exactly one app.',
         '',
         ...summaries.map((summary) => {
-            const marker = path.resolve(summary.appRoot) === path.resolve(appRoot) ? ' (current configured app)' : '';
+            const marker =
+                currentAppRoot && path.resolve(summary.appRoot) === path.resolve(currentAppRoot)
+                    ? ' (current configured app)'
+                    : '';
             const port = summary.manifest?.routerPort ? `, default port ${summary.manifest.routerPort}` : '';
             const command = createStartDevCommand({
                 appRoot: summary.appRoot,
@@ -863,7 +969,13 @@ function renderMonorepoAppRegistry({
     ];
 }
 
-function renderEmbeddedProjectInstructions({ appRoot, coreRoot, includeMonorepoRegistry = false, monorepoRoot }: TProjectInstructionArgs) {
+function renderEmbeddedProjectInstructions({
+    appRoot,
+    coreRoot,
+    includeMonorepoRegistry = false,
+    monorepoRegistryCurrentAppRoot,
+    monorepoRoot,
+}: TProjectInstructionArgs) {
     const agentSourceRoot = path.join(coreRoot, 'agents', 'project');
     if (!fs.existsSync(agentSourceRoot)) throw new Error(`Missing project instruction source root: ${agentSourceRoot}`);
 
@@ -895,7 +1007,13 @@ function renderEmbeddedProjectInstructions({ appRoot, coreRoot, includeMonorepoR
         '',
         'CLI remains the reproducible surface for `dev`, `build`, `check`, `verify`, migrations, and final command evidence. MCP remains read-only and returns compact `proteum-mcp-v1` JSON.',
         '',
-        ...(includeMonorepoRegistry ? renderMonorepoAppRegistry({ appRoot, monorepoRoot }) : []),
+        ...(includeMonorepoRegistry
+            ? renderMonorepoAppRegistry({
+                  appRoot,
+                  currentAppRoot: monorepoRegistryCurrentAppRoot,
+                  monorepoRoot,
+              })
+            : []),
         '## Always-On Safety',
         '',
         '- Never edit generated files under `.proteum`.',

package/docs/agent-routing.md

@@ -66,9 +66,9 @@ Use MCP for repeated reads when a client is available:
 proteum mcp
 ```
 
-The machine router discovers live `proteum dev` sessions and offline Proteum app roots under a cwd. `proteum dev` ensures one managed machine MCP daemon is running; terminal `proteum mcp` starts or reuses that daemon and prints a compact central MCP banner with the HTTP client URL, while MCP clients can use stdio. Agents should call MCP `workflow_start` with `cwd` or a known `projectId`, use `project_resolve { cwd }` when routing is ambiguous or offline, and pass the returned live `projectId` to every follow-up app-bound MCP tool. Offline candidates include port-inspected next actions, so agents should follow those instead of guessing the manifest default port. The router forwards to the selected dev-hosted `/__proteum/mcp` endpoint and strips routing fields before the app sees the call.
+The machine router discovers live `proteum dev` sessions and offline Proteum app roots under a cwd. `proteum dev` ensures one managed machine MCP daemon is running; terminal `proteum mcp` starts or reuses that daemon and prints a compact central MCP banner with the HTTP client URL, while MCP clients can use stdio. Agents should call MCP `workflow_start` with `cwd` or a known `projectId`, use `project_resolve { cwd }` when routing is ambiguous or offline, resolve any returned `data.readiness.state="blocked"` fresh-copy setup actions, and pass the returned live `projectId` to every follow-up app-bound MCP tool. Offline candidates include readiness and 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. In `/.codex/worktrees/`, if `workflow_start` returns a worktree bootstrap block, run `npx proteum worktree init --source <source-app-root>` or the returned `--refresh` command before any runtime read. 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`.
+If machine MCP routing returns offline candidates, choose the intended app root and follow that candidate's readiness and next actions from the app root, not from the monorepo wrapper. In `/.codex/worktrees/`, if `workflow_start` returns a worktree bootstrap block, run `npx proteum worktree init --source <source-app-root>` or the returned `--refresh` command before any runtime read. 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.
 
@@ -135,6 +135,6 @@ The latest Product `/domains` benchmark used routed instructions plus the compac
 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 `workflow_start` to collapse project resolution, fresh-copy readiness, 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/diagnostics.md

@@ -114,7 +114,7 @@ Default compact command output follows this shape:
 
 Inside `/.codex/worktrees/`, `proteum dev`, `proteum refresh`, `proteum runtime status`, `proteum verify`, and MCP `workflow_start` require a fresh `.proteum/worktree-bootstrap.json`. If the marker is missing, run `npx proteum worktree init --source <source-app-root>`. If hashes, app `.env`, workspace-root `.env` for monorepos with root tooling, `.proteum/manifest.json`, `node_modules`, or the Proteum version are stale, run the returned `npx proteum worktree init --source <source-app-root> --refresh` command. `PROTEUM_ALLOW_UNBOOTSTRAPPED_WORKTREE=1` bypasses the block but remains visible in runtime status, doctor diagnostics, and MCP output.
 
-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.
+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 fresh-copy readiness and port-inspected next actions when needed, then pass the selected live `projectId` to follow-up app-bound tools. `workflow_start` returns `data.readiness` with read-only setup checks for `.env`, dependencies, generated manifest state, connected producers, Prisma/client readiness, redacted database URL shape, and local database TCP reachability.
 
 MCP tool/resource output follows compact single-line `proteum-mcp-v1` JSON:
 
@@ -251,7 +251,7 @@ Treat these as framework contract failures first. The fix usually belongs at the
 
 For AI coding agents or automation:
 
-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`.
+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, resolve any returned `data.readiness.state="blocked"` setup actions, 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.

package/docs/mcp.md

@@ -28,7 +28,7 @@ The router is read-only. It does not start or stop dev servers, mutate files, re
 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`.
+2. If the result is ambiguous or returns offline app candidates, call `project_resolve { cwd }`, pick the intended app root, resolve any returned `data.readiness.state="blocked"` setup actions, 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.
 
@@ -47,7 +47,7 @@ Example tool calls:
 {"tool":"db_query","arguments":{"projectId":"prj_0123abcd4567","sql":"SELECT id, email FROM User LIMIT 5","limit":5}}
 ```
 
-`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.
+`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. Its machine-router response includes `data.readiness`, a read-only fresh-copy preflight covering app/root `.env` files, dependency install root and package manager, generated Proteum manifest state, local connected producer apps, Prisma schema/client readiness, redacted database URL shape, and local TCP database reachability when the host is local. The preflight adds exact setup commands where safe, such as copying `.env.example`, installing dependencies, running `npx proteum refresh`, generating Prisma Client, checking Prisma migration status, preflighting connected producer apps, and starting `proteum dev` on a checked port. 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.
 
 When the selected app root is inside `/.codex/worktrees/`, `workflow_start` first checks `.proteum/worktree-bootstrap.json`. If the marker is missing or stale, it returns `ok: false` with a single next action such as `npx proteum worktree init --source <source-app-root>` or the same command with `--refresh`. The router does not forward to the app MCP endpoint until bootstrap is complete, unless `PROTEUM_ALLOW_UNBOOTSTRAPPED_WORKTREE=1` is set; bypasses remain visible in MCP, `runtime status`, and `doctor`.
 
@@ -79,9 +79,10 @@ 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 the app root is inside `/.codex/worktrees/` and runtime status or workflow start reports missing/stale bootstrap, run `proteum worktree init --source <source-app-root>` or the returned `--refresh` command first.
-4. 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.
-5. 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.
-6. Retry MCP `workflow_start` and use the returned `projectId`.
+4. If `workflow_start` returns `data.readiness.state="blocked"`, run or resolve the readiness setup actions before starting dev.
+5. If no live app session exists, use the exact Start Dev next action returned by runtime status or `workflow_start`. It checks the configured router/HMR ports and suggests an alternate free port when the manifest default is occupied.
+6. 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.
+7. 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.
 
@@ -122,7 +123,7 @@ 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 |
+| `workflow_start` | One-call bootstrap with resolved project, fresh-copy readiness, 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 and full-read policy |

package/docs/request-tracing.md

@@ -33,7 +33,7 @@ proteum perf memory --since 1h --group-by controller
 
 Default trace output is compact `proteum-agent-v1` JSON with counts, failed calls, error events, hot calls, and hot SQL. Use `--events` or `--full` only when raw event details, payload summaries, or SQL text are needed.
 
-When an MCP client is available, call `workflow_start` with `cwd` or a known `projectId`, then use the returned live `projectId` with MCP `trace_latest`, `trace_show`, `perf_top`, and `perf_request` for repeated reads against the same running app. If `workflow_start` returns offline app candidates or unreachable runtime health, start or repair exactly one `proteum dev` server from the intended app root before trace or perf reads. Keep the CLI commands for reproducible terminal evidence and final verification logs.
+When an MCP client is available, call `workflow_start` with `cwd` or a known `projectId`, then use the returned live `projectId` with MCP `trace_latest`, `trace_show`, `perf_top`, and `perf_request` for repeated reads against the same running app. If `workflow_start` returns offline app candidates, `data.readiness.state="blocked"`, or unreachable runtime health, resolve the readiness setup actions and start or repair exactly one `proteum dev` server from the intended app root before trace or perf reads. Keep the CLI commands for reproducible terminal evidence and final verification logs.
 
 Before reproducing a bug or starting a new test pass:
 

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "proteum",
 	"description": "LLM-first Opinionated Typescript Framework for web applications.",
-	"version": "2.5.4",
+	"version": "2.5.6",
 	"author": "Gaetan Le Gac (https://github.com/gaetanlegac)",
 	"repository": "git://github.com/gaetanlegac/proteum.git",
 	"license": "MIT",