proteum 2.5.4 → 2.5.6

package/AGENTS.md

@@ -45,7 +45,7 @@ npx prisma migrate dev --config ./prisma.config.ts --name <migration name>
 
   [optional body]
   ```
-  If the user replies exactly `commit`, treat it as conversation-wide and cross-project, not task-scoped. Identify every affected git repository or worktree touched since the last `commit` and, if there has been no prior `commit`, since the beginning of the whole conversation. In each affected repository or worktree, stage all conversation-related changed files with `git add` while still excluding unrelated pre-existing user changes or incidental untracked files, then create one `git commit`. Do not omit linked local dependencies, framework repos, connected projects, or producer apps when they were changed to make the delivered behavior actually work.
+  If the user replies exactly `commit`, treat it as conversation-wide and cross-project, not task-scoped. Identify every affected git repository or worktree touched since the last `commit` and, if there has been no prior `commit`, since the beginning of the whole conversation. In each affected repository or worktree, stage all conversation-related changed files with `git add` while still excluding unrelated pre-existing user changes or incidental untracked files, then create one `git commit`. Do not run downstream project commit-time verification such as `proteum refresh`, targeted lint, typecheck, or test commands when committing this framework repository itself unless the user explicitly asks for those checks. Do not omit linked local dependencies, framework repos, connected projects, or producer apps when they were changed to make the delivered behavior actually work.
   When the user asks to push, explain the currently unpushed commits in short, minimalistic bullet points in plain language, like you would do to your grandma. Start each bullet with a verb in the past.
   When an optional commit body is useful, write it as a short, minimalistic bullet list explaining what changed in this thread in plain language, like you would do to your grandma. Start each bullet with a verb in the past. Do not print a separate prompt asking for that explanation.
 

package/README.md

@@ -473,7 +473,7 @@ Every `proteum dev` start runs the same idempotent instruction check. It updates
 
 `proteum worktree init` writes `.proteum/worktree-bootstrap.json` for app roots under `/.codex/worktrees/`. The marker records `.env` copy status, refresh and dependency results, runtime status, key file hashes, and the active Proteum version. In monorepos with root tooling such as `prisma.config.ts` or npm workspaces, bootstrap also ensures the workspace-root `.env` exists, copying the source root `.env` when available or falling back to the source app `.env`. `proteum dev`, `proteum refresh`, `proteum runtime status`, `proteum verify`, and MCP `workflow_start` block inside Codex worktrees until the marker is fresh. Run `npx proteum worktree init --source <source-app-root>` for a new worktree, or add `--refresh` when stale state is reported. `PROTEUM_ALLOW_UNBOOTSTRAPPED_WORKTREE=1` bypasses the block but remains visible in runtime status, doctor, and MCP output.
 
-`proteum connect`, `proteum explain`, `proteum doctor`, and `proteum diagnose` share the same generated manifest and contract state. `proteum perf` uses the same dev request-trace store as the profiler `Perf` tab. `proteum runtime status` also inspects the configured router/HMR ports and returns an exact Start Dev action, so agents do not need to `curl` page routes to identify port owners. `proteum dev` exposes the app-root MCP contract at `/__proteum/mcp` and ensures one managed machine MCP daemon is running; `proteum mcp` is the machine-scope router agents register once. Agents should start with MCP `workflow_start`, use offline candidates to choose the correct app root when no dev server is live, then route repeated reads by the returned live `projectId`. For the full diagnostics and tracing model, see [docs/diagnostics.md](docs/diagnostics.md), [docs/mcp.md](docs/mcp.md), and [docs/request-tracing.md](docs/request-tracing.md).
+`proteum connect`, `proteum explain`, `proteum doctor`, and `proteum diagnose` share the same generated manifest and contract state. `proteum perf` uses the same dev request-trace store as the profiler `Perf` tab. `proteum runtime status` also inspects the configured router/HMR ports and returns an exact Start Dev action, so agents do not need to `curl` page routes to identify port owners. `proteum dev` exposes the app-root MCP contract at `/__proteum/mcp` and ensures one managed machine MCP daemon is running; `proteum mcp` is the machine-scope router agents register once. Agents should start with MCP `workflow_start`, use offline candidates and `data.readiness` to choose and prepare the correct app root when no dev server is live, then route repeated reads by the returned live `projectId`. For the full diagnostics and tracing model, see [docs/diagnostics.md](docs/diagnostics.md), [docs/mcp.md](docs/mcp.md), and [docs/request-tracing.md](docs/request-tracing.md).
 
 ## Dev Commands
 
@@ -597,15 +597,16 @@ Proteum answers those questions with explicit artifacts:
 If you are an LLM or automation agent, start here:
 
 1. Use `proteum mcp` as the one registered MCP server; `proteum dev` ensures the managed machine daemon is running.
-2. Call MCP `workflow_start` with `cwd` or a known `projectId`; if it is ambiguous or returns offline app candidates, use `project_resolve { cwd }`, choose the intended app root, follow its port-inspected next action when needed, then retry `workflow_start`.
-3. If the app root is inside `/.codex/worktrees/` and `workflow_start` or a guarded CLI command reports missing/stale bootstrap, run the returned `npx proteum worktree init --source <source-app-root>` command before runtime reads.
-4. Use the returned live `projectId` with MCP `runtime_status`, `orient`, `instructions_resolve`, `route_candidates`, `explain_summary`, `diagnose`, `trace_show`, `perf_request`, and `logs_tail` before CLI equivalents for repeated read-only app state.
-5. Treat returned instruction previews as the allowed scope for read-only discovery and diagnostics. Read full file contents only before edits or git writes, when `fullRead`/`fullReadPolicy` requires it, or when compact previews are insufficient.
-6. Use compact CLI commands for fallback, `dev`, `build`, `check`, `verify`, migrations, E2E, and final reproducible terminal evidence.
-7. Use `proteum diagnose`, `proteum perf`, and compact `proteum trace` for reproducible command evidence when MCP is unavailable or the terminal output itself is needed.
-8. 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 MCP offline or runtime-status next action. If the same app already responds on the configured port without live tracking, use or repair that runtime instead of starting another server. If a live session exists but runtime/MCP is unreachable, stop the listed session file first, then start dev again and retry `workflow_start`. Do not run diagnose, trace, or perf reads while runtime health is unreachable, and do not `curl` normal page routes to identify port ownership.
-9. Inspect `server/index.ts`, controllers, services, or pages only after the routing/diagnostic surfaces identify the relevant owner. Do not run broad owner searches after MCP already returned the route/page/controller owner.
-10. If the task touches a protected route or controller in dev and login UX is not the feature under test, use `proteum e2e --session-email <email> --session-role <role>` for Playwright suites or `proteum session <email> --role <role>` before direct HTTP calls.
+2. Call MCP `workflow_start` with `cwd` or a known `projectId`; if it is ambiguous or returns offline app candidates, use `project_resolve { cwd }`, choose the intended app root, follow its fresh-copy readiness and port-inspected next actions when needed, then retry `workflow_start`.
+3. If `workflow_start` returns `data.readiness.state="blocked"`, resolve the returned setup actions first. The read-only readiness preflight covers app/root `.env`, dependency install root, generated manifest state, local connected producer apps, Prisma/client readiness, redacted database URL shape, local database TCP reachability, and exact safe setup commands.
+4. If the app root is inside `/.codex/worktrees/` and `workflow_start` or a guarded CLI command reports missing/stale bootstrap, run the returned `npx proteum worktree init --source <source-app-root>` command before runtime reads.
+5. Use the returned live `projectId` with MCP `runtime_status`, `orient`, `instructions_resolve`, `route_candidates`, `explain_summary`, `diagnose`, `trace_show`, `perf_request`, and `logs_tail` before CLI equivalents for repeated read-only app state.
+6. Treat returned instruction previews as the allowed scope for read-only discovery and diagnostics. Read full file contents only before edits or git writes, when `fullRead`/`fullReadPolicy` requires it, or when compact previews are insufficient.
+7. Use compact CLI commands for fallback, `dev`, `build`, `check`, `verify`, migrations, E2E, and final reproducible terminal evidence.
+8. Use `proteum diagnose`, `proteum perf`, and compact `proteum trace` for reproducible command evidence when MCP is unavailable or the terminal output itself is needed.
+9. 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 MCP offline or runtime-status next action. If the same app already responds on the configured port without live tracking, use or repair that runtime instead of starting another server. If a live session exists but runtime/MCP is unreachable, stop the listed session file first, then start dev again and retry `workflow_start`. Do not run diagnose, trace, or perf reads while runtime health is unreachable, and do not `curl` normal page routes to identify port ownership.
+10. Inspect `server/index.ts`, controllers, services, or pages only after the routing/diagnostic surfaces identify the relevant owner. Do not run broad owner searches after MCP already returned the route/page/controller owner.
+11. If the task touches a protected route or controller in dev and login UX is not the feature under test, use `proteum e2e --session-email <email> --session-role <role>` for Playwright suites or `proteum session <email> --role <role>` before direct HTTP calls.
 
 For implementation rules in a real Proteum app, treat the routed local `AGENTS.md` files plus `proteum orient`, compact CLI diagnostics, and MCP repeated-read surfaces as the task contract. This README is the framework overview, not the project-local instruction layer.
 

package/agents/project/AGENTS.md

@@ -31,7 +31,7 @@ Managed compact root routers must use trigger -> canonical instruction file refe
 - If the user asks to implement a feature, first inspect the relevant existing surface and state any implementation problem, pain point, attention point, inconsistency, missing information, or question you see. If anything needs clarification or a decision, pause before editing, ask the user what decision to take, and resume only after the user answers.
 - If the task is ambiguous, generated, connected, or multi-repo, start with MCP `workflow_start` and then MCP `orient { projectId, query }` only if the bootstrap did not return a sufficient owner or next action; use `npx proteum orient <query>` only when MCP is unavailable or terminal evidence is required.
 - Treat Proteum CLI and MCP output as the workflow router. Treat instruction previews returned by MCP `workflow_start` or `instructions_resolve { projectId }` as the allowed instruction scope for read-only discovery and diagnostics. Read full file contents only before edits or git writes, when returned `fullRead`/`fullReadPolicy` requires it, or when the compact preview is insufficient. Do not read broad instruction folders or every managed instruction file up front.
-- When a Proteum MCP client is available, first call MCP `workflow_start` with `cwd` or a known `projectId`. If it is ambiguous or returns offline app candidates, call `project_resolve { cwd }`, select the intended app root, start exactly one dev server from that app root when needed, then retry `workflow_start`. Pass the returned live `projectId` to every follow-up app-bound MCP tool. `npx proteum dev` ensures one managed machine MCP daemon is running; do not start a second managed daemon. Prefer MCP `runtime_status`, `orient`, `instructions_resolve`, `explain_summary`, `route_candidates`, `doctor`, `diagnose`, `trace_show`, `perf_request`, `logs_tail`, and `db_query` for read-only runtime/status/orientation/owner/route/trace/perf/log/database reads. Do not run CLI equivalents after a successful MCP result for the same read. Do not run broad source searches for route/page/controller ownership after MCP returns the owner. Use CLI commands when you need reproducible terminal validation, dev/build/check workflows, fallback repair, or output to share with a human.
+- When a Proteum MCP client is available, first call MCP `workflow_start` with `cwd` or a known `projectId`. If it is ambiguous or returns offline app candidates, call `project_resolve { cwd }`, select the intended app root, resolve any returned `data.readiness.state="blocked"` fresh-copy setup actions, start exactly one dev server from that app root when needed, then retry `workflow_start`. Pass the returned live `projectId` to every follow-up app-bound MCP tool. `npx proteum dev` ensures one managed machine MCP daemon is running; do not start a second managed daemon. Prefer MCP `runtime_status`, `orient`, `instructions_resolve`, `explain_summary`, `route_candidates`, `doctor`, `diagnose`, `trace_show`, `perf_request`, `logs_tail`, and `db_query` for read-only runtime/status/orientation/owner/route/trace/perf/log/database reads. Do not run CLI equivalents after a successful MCP result for the same read. Do not run broad source searches for route/page/controller ownership after MCP returns the owner. Use CLI commands when you need reproducible terminal validation, dev/build/check workflows, fallback repair, or output to share with a human.
 - MCP payloads are compact single-line `proteum-mcp-v1` JSON with capped and paginated detail. Do not expand MCP output for human readability.
 - For every non-trivial coding task, load and follow root-level `DOCUMENTATION.md` before coding.
 - For bug fixes, regressions, incidents, broken public routes, auth/OAuth failures, integration failures, or production behavior fixes, load and follow root-level `DOCUMENTATION.md` before coding so the relevant fix note, regression-test docs, ADR, or explicit skip reason is handled in the same change.
@@ -53,7 +53,7 @@ Managed compact root routers must use trigger -> canonical instruction file refe
 
   [optional body]
   ```
-  Then treat `commit` as conversation-wide and cross-project, not task-scoped. Do not run any check, lint, typecheck, test, coverage, or commit gate as part of this exact `commit` workflow unless the user explicitly asks for those checks in the same request. Identify every affected git repository or worktree touched during that span, stage all conversation-related changed files in each affected repository or worktree with `git add` while still avoiding unrelated pre-existing user changes or incidental untracked files, and create one `git commit` per affected repository or worktree. Do not omit linked local dependencies, framework repos, connected projects, or producer apps when they were changed to make the delivered behavior actually work. Do not stop at only suggesting the message.
+  Then treat `commit` as conversation-wide and cross-project, not task-scoped. For downstream Proteum apps, before staging or committing, run only this commit-time verification: `proteum refresh`, then the targeted lint, typecheck, and test commands that match the conversation changes in parallel. Skip this downstream app verification when the affected repository is the Proteum framework repository itself; use the framework repo `AGENTS.md` commit workflow there. Do not run coverage, full `npm run check`, repository `check:commit`, unrelated broad suites, or any other check unless the user explicitly asks for it in the same request. Report any blocker instead of committing through failed commit-time verification. Identify every affected git repository or worktree touched during that span, stage all conversation-related changed files in each affected repository or worktree with `git add` while still avoiding unrelated pre-existing user changes or incidental untracked files, and create one `git commit` per affected repository or worktree. Do not omit linked local dependencies, framework repos, connected projects, or producer apps when they were changed to make the delivered behavior actually work. Do not stop at only suggesting the message.
   After providing a commit message or after creating a commit, immediately follow it with this exact prompt and obey it:
   `Explain in short minimalistic and few bullet points what we changed in this thread, like you would do to your grandma. Start with a verb in the past.`
 
@@ -80,7 +80,7 @@ Managed compact root routers must use trigger -> canonical instruction file refe
 
 - Before finishing, re-check touched files against root-level `CODING_STYLE.md` and any narrower area `AGENTS.md` that applied to the edit. Re-check against root-level `optimizations.md` only for touched client-side files. Re-check against root-level `diagnostics.md` only if the task involved an issue, diagnosis, runtime reproduction, or verification failure.
 - Before finishing a production code change, re-check root-level `DOCUMENTATION.md` update rules. If behavior changed, a bug was fixed, a decision changed, or an important route, auth/OAuth, or integration issue was addressed, update the relevant docs before committing or explicitly explain why no docs update was needed.
-- Run targeted tests and checks that match the changed surface before finishing each feature or change. When the repository defines `proteum.verify.config.ts`, use `npx proteum verify changed` as the first post-change verification pass and expand only when the selected plan is insufficient. Continue running tests after changes, but do not run coverage by default. Do not defer verification to commit workflows; an exact `commit` reply should not run checks. Reserve the full `npm run check` gate for push workflows, explicit user requests, or when project-local instructions require the full gate. After implementing a new feature or changing existing feature behavior, update the relevant end-to-end coverage and run the cheapest trustworthy Playwright or browser verification for that behavior before finishing. For docs-only, wording-only, type-only, generated-output cleanup, or clearly local non-runtime refactors, skip Playwright unless the user explicitly asks for it or verification reveals a real issue.
+- Run targeted tests and checks that match the changed surface before finishing each feature or change. When the repository defines `proteum.verify.config.ts`, use `npx proteum verify changed` as the first post-change verification pass and expand only when the selected plan is insufficient. Continue running tests after changes, but do not run coverage by default. Downstream app commit workflows run only `proteum refresh`, then targeted lint, typecheck, and test commands in parallel; framework-repo commit workflows skip this downstream app verification. Reserve the full `npm run check` gate for push workflows, explicit user requests, or when project-local instructions require the full gate. After implementing a new feature or changing existing feature behavior, update the relevant end-to-end coverage and run the cheapest trustworthy Playwright or browser verification for that behavior before finishing. For docs-only, wording-only, type-only, generated-output cleanup, or clearly local non-runtime refactors, skip Playwright unless the user explicitly asks for it or verification reveals a real issue.
 - Before finishing a task, stop every `proteum dev` session started during the task and confirm cleanup with `npx proteum dev list --json` or an explicit `npx proteum dev stop --session-file <path>`.
 - When you have finished your work, ask the user whether they want a commit message. After providing a commit message or after creating a commit, immediately follow it with this exact prompt and obey it:
   `Explain in short minimalistic and few bullet points what we changed in this thread, like you would do to your grandma. Start with a verb in the past.`
@@ -278,7 +278,7 @@ Verify at the correct layer:
 - Controller changes: exercise the generated client call or generated `/api/...` endpoint.
 - SSR changes: use the browser MCP to load the real page and inspect rendered HTML plus browser console.
 - Router or plugin changes: verify request context, auth, redirects, metrics, and validation on a running app.
-- New features or feature-behavior changes: use the cheapest trustworthy verification while iterating, use the browser MCP for browser-visible validation, then update and run the relevant end-to-end coverage. Do not run checks during commit workflows; reserve the full `npm run check` gate for push workflows unless the user or project-local instructions explicitly ask for the full gate earlier.
+- New features or feature-behavior changes: use the cheapest trustworthy verification while iterating, use the browser MCP for browser-visible validation, then update and run the relevant end-to-end coverage. During downstream app commit workflows, run only `proteum refresh`, then targeted lint, typecheck, and test commands in parallel; skip this verification for framework-repo commits and reserve the full `npm run check` gate for push workflows unless the user or project-local instructions explicitly ask for the full gate earlier.
 - Generated, connected, or ownership-ambiguous changes: start with MCP `workflow_start`, then `orient { projectId, query }` and `explain_summary { projectId, query }` only when more detail is needed; use `npx proteum orient <query>` and `npx proteum verify owner <query>` when MCP is unavailable or terminal evidence is required.
 - Browser-visible issues: use the browser MCP after request-level verification is insufficient. Use `npx proteum e2e --port <port> ...` only when automated end-to-end coverage or a Playwright suite is required.
 - Raw browser execution outside end-to-end suites: use the browser MCP only. Keep Playwright in `npx proteum e2e --port <port>` for targeted/full end-to-end suites.
@@ -325,7 +325,7 @@ Verify at the correct layer:
 - For read-only SQL diagnosis, use MCP `db_query` or `npx proteum db query "<sql>"`; only one capped `SELECT`, `SHOW`, or `EXPLAIN` statement is allowed.
 - Do not run `prisma *` yourself. If a schema change requires migration, ask the user to run `npx prisma migrate dev --config ./prisma.config.ts --name <migration name>` and wait for `continue`.
 - Do not run `git restore` or `git reset`.
-- Do not run write-mode git commands by default. The built-in exception is an exact `commit` reply, which allows `git add` and `git commit` in every affected repository or worktree touched during the whole conversation. An exact `commit` reply does not allow check, lint, typecheck, test, coverage, or commit-gate commands unless the user explicitly requests them in the same message. Any other write-mode git action requires an explicit user request. Before any explicit push, run `npm run check` in every affected repository or worktree that defines it and report any blocker instead of pushing through a failed check.
+- Do not run write-mode git commands by default. The built-in exception is an exact `commit` reply, which allows `git add` and `git commit` in every affected repository or worktree touched during the whole conversation after the applicable commit-time verification succeeds. For downstream apps, commit-time verification is limited to `proteum refresh`, then targeted lint, typecheck, and test commands in parallel. For the Proteum framework repository itself, skip this downstream app verification and use the framework repo `AGENTS.md` commit workflow. This exception does not allow coverage, full `npm run check`, repository `check:commit`, unrelated broad suites, or other checks unless the user explicitly requests them in the same message. Any other write-mode git action requires an explicit user request. Before any explicit push, run `npm run check` in every affected repository or worktree that defines it and report any blocker instead of pushing through a failed check.
 
 ## Appendix
 
@@ -423,7 +423,7 @@ Agents working in generated Proteum projects must use this delivery workflow for
 4. Targeted validation: refresh generated framework contracts after route, page, controller, service, command, or config changes, then run the targeted tests/checks that match the changed surface.
 5. Validate unit + E2E: run the relevant unit tests and real-world journey E2E checks before calling the work complete.
 
-Unit test expectation: production changes must always add or update focused unit tests and run the targeted unit or integration tests that match the changed behavior. Do not run coverage after every change by default. Reserve whole-project coverage for the repository's full `npm run check` gate during push workflows or when the user explicitly requests it; do not run checks for commit-only workflows unless the user explicitly requests them. Any excluded generated files, migrations, framework shims, unreachable defensive branches, or changes that cannot reasonably be unit-tested must be documented in the completion note.
+Unit test expectation: production changes must always add or update focused unit tests and run the targeted unit or integration tests that match the changed behavior. Do not run coverage after every change by default. Reserve whole-project coverage for the repository's full `npm run check` gate during push workflows or when the user explicitly requests it; downstream app commit-only workflows run `proteum refresh`, then targeted lint, typecheck, and test commands in parallel unless the user explicitly requests more, while framework-repo commits skip this downstream app verification. Any excluded generated files, migrations, framework shims, unreachable defensive branches, or changes that cannot reasonably be unit-tested must be documented in the completion note.
 
 E2E expectation: real-world journeys must follow the project-local instructions in `tests/e2e/REAL_WORLD_JOURNEY_TESTS.md`. These tests should model complete user workflows, role transitions, permissions, state changes, and cross-view consistency rather than isolated happy paths.
 

package/agents/project/CODING_STYLE.md

@@ -8,7 +8,7 @@ This file is the source of truth for codex coding style instructions in Proteum-
 - Write clean, consistent, readable code with a tab size of 4.
 - Keep functions and methods short.
 - Every time possible, create reusable functions and components instead of repeating.
-- Before finishing a feature or change, review touched files against this document and run targeted lint/typecheck/tests for the changed surface. When the repository defines `proteum.verify.config.ts`, use `npx proteum verify changed` as the first post-change verification pass. Do not run coverage by default after ordinary changes. Do not run check, lint, typecheck, test, coverage, or commit-gate commands as part of a commit-only workflow; run the full `npm run check` gate before pushing or when the user explicitly asks for it. Coding-style regressions are defects, not optional cleanup.
+- Before finishing a feature or change, review touched files against this document and run targeted lint/typecheck/tests for the changed surface. When the repository defines `proteum.verify.config.ts`, use `npx proteum verify changed` as the first post-change verification pass. Do not run coverage by default after ordinary changes. Downstream app commit-only workflows run only `proteum refresh`, then targeted lint, typecheck, and test commands in parallel; framework-repo commit workflows skip this downstream app verification. Run the full `npm run check` gate before pushing or when the user explicitly asks for it. Coding-style regressions are defects, not optional cleanup.
 
 ## Type safety
 

package/agents/project/diagnostics.md

@@ -4,7 +4,7 @@ This file is the canonical source of truth for diagnostics, temporary instrument
 
 ## Initial Triage
 
-- Start with compact machine-readable app state before reading large parts of the codebase. When a Proteum MCP client is available, call MCP `workflow_start` with `cwd` or a known `projectId`; if it is ambiguous or returns offline app candidates, call `project_resolve { cwd }`, select the intended app root, start exactly one dev server from that app root when needed, then retry `workflow_start`. Use the returned live `projectId` for follow-up MCP `runtime_status`, `orient`, `instructions_resolve`, `explain_summary`, `route_candidates`, `doctor`, `diagnose`, `trace_latest`, `trace_show`, `perf_top`, `perf_request`, `logs_tail`, and `db_query`.
+- Start with compact machine-readable app state before reading large parts of the codebase. When a Proteum MCP client is available, call MCP `workflow_start` with `cwd` or a known `projectId`; if it is ambiguous or returns offline app candidates, call `project_resolve { cwd }`, select the intended app root, resolve any returned `data.readiness.state="blocked"` fresh-copy setup actions, start exactly one dev server from that app root when needed, then retry `workflow_start`. Use the returned live `projectId` for follow-up MCP `runtime_status`, `orient`, `instructions_resolve`, `explain_summary`, `route_candidates`, `doctor`, `diagnose`, `trace_latest`, `trace_show`, `perf_top`, `perf_request`, `logs_tail`, and `db_query`.
 - Do not run CLI equivalents after a successful MCP result for the same read. Do not run broad source searches for route/page/controller ownership after MCP returns the owner. Use compact CLI commands such as `npx proteum orient <query>`, `npx proteum runtime status`, `npx proteum connect`, `npx proteum explain`, `npx proteum doctor`, and `npx proteum doctor --contracts` when MCP is unavailable, when generated artifacts or manifest-owned files may be stale, or when you need a reproducible shell command, validation step, or CI-like output.
 - MCP payloads are compact `proteum-mcp-v1` JSON and are capped/paginated by default. Use selected instruction previews for read-only discovery and diagnostics; read full files or request full MCP detail only when returned `fullRead`/`fullReadPolicy` or omitted-detail hints require it.
 - Use full-detail escape hatches only after compact output identifies the missing detail: `npx proteum explain --manifest`, `npx proteum diagnose <target> --full`, `npx proteum trace show <requestId> --events`, or `npx proteum perf request <requestId> --full`.
@@ -64,7 +64,7 @@ This file is the canonical source of truth for diagnostics, temporary instrument
 - For browser regressions, prefer a browser MCP repro first and add targeted Playwright E2E coverage only when the user asks for automated coverage, when a stable regression path needs automation, or when browser MCP verification is insufficient.
 - Only the final verifier agent should usually run browser flows. Earlier agents should stay on `orient`, `verify owner`, `verify request`, `diagnose`, and command-level checks unless browser execution is the only trustworthy reproducer.
 - Treat server startup failures, runtime errors, browser console errors or warnings, and Playwright failures as blocking unless they are clearly unrelated to the change.
-- When the touched surface can affect coding-style enforcement, run the targeted lint or typecheck command for that surface before finishing. Do not run check, lint, typecheck, test, coverage, or commit-gate commands as part of a commit-only workflow. Run the full `npm run check` gate before pushing or when explicitly requested.
+- When the touched surface can affect coding-style enforcement, run the targeted lint or typecheck command for that surface before finishing. Downstream app commit-only workflows run only `proteum refresh`, then targeted lint, typecheck, and test commands in parallel; framework-repo commit workflows skip this downstream app verification. Run the full `npm run check` gate before pushing or when explicitly requested.
 - If the task started any long-lived `proteum dev` server, stop it explicitly with `npx proteum dev stop --session-file <path>` or `npx proteum dev stop --all --stale`, then confirm the remaining tracked sessions with `npx proteum dev list --json`.
 - Add `data-testid` when stable selectors are missing instead of relying on brittle text or DOM-shape selectors.
 - If an isolated test misses prerequisite state, run the smallest broader scope that reproduces the real setup.

package/agents/project/root/AGENTS.md

@@ -18,7 +18,7 @@ Managed compact root routers must use trigger -> canonical instruction file refe
 - If the user asks to implement a feature, first inspect the relevant existing surface and state any implementation problem, pain point, attention point, inconsistency, missing information, or question you see. If anything needs clarification or a decision, pause before editing, ask the user what decision to take, and resume only after the user answers.
 - If the task is ambiguous, generated, connected, or multi-repo, start with MCP `workflow_start` and then MCP `orient { projectId, query }` only if the bootstrap did not return a sufficient owner or next action; use `npx proteum orient <query>` only when MCP is unavailable or terminal evidence is required.
 - Treat Proteum CLI and MCP output as the workflow router. Treat instruction previews returned by MCP `workflow_start` or `instructions_resolve { projectId }` as the allowed instruction scope for read-only discovery and diagnostics. Read full file contents only before edits or git writes, when returned `fullRead`/`fullReadPolicy` requires it, or when the compact preview is insufficient. Do not read broad instruction folders or every managed instruction file up front.
-- When a Proteum MCP client is available, first call MCP `workflow_start` with `cwd` or a known `projectId`. If it is ambiguous or returns offline app candidates, call `project_resolve { cwd }`, select the intended app root, start exactly one dev server from that app root when needed, then retry `workflow_start`. Pass the returned live `projectId` to every follow-up app-bound MCP tool. `npx proteum dev` ensures one managed machine MCP daemon is running; do not start a second managed daemon. Prefer MCP `runtime_status`, `orient`, `instructions_resolve`, `explain_summary`, `route_candidates`, `doctor`, `diagnose`, `trace_show`, `perf_request`, `logs_tail`, and `db_query` for read-only runtime/status/orientation/owner/route/trace/perf/log/database reads. Do not run CLI equivalents after a successful MCP result for the same read. Do not run broad source searches for route/page/controller ownership after MCP returns the owner. Use CLI commands when you need reproducible terminal validation, dev/build/check workflows, fallback repair, or output to share with a human.
+- When a Proteum MCP client is available, first call MCP `workflow_start` with `cwd` or a known `projectId`. If it is ambiguous or returns offline app candidates, call `project_resolve { cwd }`, select the intended app root, resolve any returned `data.readiness.state="blocked"` fresh-copy setup actions, start exactly one dev server from that app root when needed, then retry `workflow_start`. Pass the returned live `projectId` to every follow-up app-bound MCP tool. `npx proteum dev` ensures one managed machine MCP daemon is running; do not start a second managed daemon. Prefer MCP `runtime_status`, `orient`, `instructions_resolve`, `explain_summary`, `route_candidates`, `doctor`, `diagnose`, `trace_show`, `perf_request`, `logs_tail`, and `db_query` for read-only runtime/status/orientation/owner/route/trace/perf/log/database reads. Do not run CLI equivalents after a successful MCP result for the same read. Do not run broad source searches for route/page/controller ownership after MCP returns the owner. Use CLI commands when you need reproducible terminal validation, dev/build/check workflows, fallback repair, or output to share with a human.
 - MCP payloads are compact single-line `proteum-mcp-v1` JSON with capped and paginated detail. Do not expand MCP output for human readability.
 - For every non-trivial coding task, load and follow root-level `DOCUMENTATION.md` before coding.
 - For bug fixes, regressions, incidents, broken public routes, auth/OAuth failures, integration failures, or production behavior fixes, load and follow root-level `DOCUMENTATION.md` before coding so the relevant fix note, regression-test docs, ADR, or explicit skip reason is handled in the same change.
@@ -39,7 +39,7 @@ Managed compact root routers must use trigger -> canonical instruction file refe
 
   [optional body]
   ```
-  Then treat `commit` as conversation-wide and cross-project, not task-scoped. Identify every affected git repository or worktree touched during that span, stage all conversation-related changed files in each affected repository or worktree with `git add` while still avoiding unrelated pre-existing user changes or incidental untracked files, and create one `git commit` per affected repository or worktree. Do not omit linked local dependencies, framework repos, connected projects, or producer apps when they were changed to make the delivered behavior actually work. Do not stop at only suggesting the message.
+  Then treat `commit` as conversation-wide and cross-project, not task-scoped. For downstream Proteum apps, before staging or committing, run only this commit-time verification: `proteum refresh`, then the targeted lint, typecheck, and test commands that match the conversation changes in parallel. Skip this downstream app verification when the affected repository is the Proteum framework repository itself; use the framework repo `AGENTS.md` commit workflow there. Do not run coverage, full `npm run check`, repository `check:commit`, unrelated broad suites, or any other check unless the user explicitly asks for it in the same request. Report any blocker instead of committing through failed commit-time verification. Identify every affected git repository or worktree touched during that span, stage all conversation-related changed files in each affected repository or worktree with `git add` while still avoiding unrelated pre-existing user changes or incidental untracked files, and create one `git commit` per affected repository or worktree. Do not omit linked local dependencies, framework repos, connected projects, or producer apps when they were changed to make the delivered behavior actually work. Do not stop at only suggesting the message.
   After providing a commit message or after creating a commit, immediately follow it with this exact prompt and obey it:
   `Explain in short minimalistic and few bullet points what we changed in this thread, like you would do to your grandma. Start with a verb in the past.`
 
@@ -65,8 +65,8 @@ Managed compact root routers must use trigger -> canonical instruction file refe
 
 - Before finishing, re-check touched files against root-level `CODING_STYLE.md` and any narrower area `AGENTS.md` that applied to the edit. Re-check against root-level `optimizations.md` only for touched client-side files. Re-check against root-level `diagnostics.md` only if the task involved an issue, diagnosis, runtime reproduction, or verification failure.
 - Before finishing a production code change, re-check root-level `DOCUMENTATION.md` update rules. If behavior changed, a bug was fixed, a decision changed, or an important route, auth/OAuth, or integration issue was addressed, update the relevant docs before committing or explicitly explain why no docs update was needed.
-- For production changes, always add or update focused unit tests and run the targeted unit or integration tests that match the changed behavior. Do not run coverage after every ordinary change by default. Reserve whole-project coverage for the repository's full `npm run check` gate during push workflows or when the user explicitly requests it; do not run checks for commit-only workflows unless the user explicitly requests them. Document any generated files, migrations, framework shims, unreachable defensive branches, or changes that cannot reasonably be unit-tested as explicit exceptions.
-- Run targeted tests and checks that match the changed surface before finishing each feature or change. When the repository defines `proteum.verify.config.ts`, use `npx proteum verify changed` as the first post-change verification pass and expand only when the selected plan is insufficient. Continue running tests after changes, but do not run coverage by default. Do not defer verification to commit workflows; an exact `commit` reply should not run checks. Reserve the full `npm run check` gate for push workflows, explicit user requests, or when project-local instructions require the full gate. After implementing a new feature or changing existing feature behavior, update the relevant end-to-end coverage and run the cheapest trustworthy Playwright or browser verification for that behavior before finishing. For docs-only, wording-only, type-only, generated-output cleanup, or clearly local non-runtime refactors, skip Playwright unless the user explicitly asks for it or verification reveals a real issue.
+- For production changes, always add or update focused unit tests and run the targeted unit or integration tests that match the changed behavior. Do not run coverage after every ordinary change by default. Reserve whole-project coverage for the repository's full `npm run check` gate during push workflows or when the user explicitly requests it; downstream app commit-only workflows run `proteum refresh`, then targeted lint, typecheck, and test commands in parallel unless the user explicitly requests more, while framework-repo commits skip this downstream app verification. Document any generated files, migrations, framework shims, unreachable defensive branches, or changes that cannot reasonably be unit-tested as explicit exceptions.
+- Run targeted tests and checks that match the changed surface before finishing each feature or change. When the repository defines `proteum.verify.config.ts`, use `npx proteum verify changed` as the first post-change verification pass and expand only when the selected plan is insufficient. Continue running tests after changes, but do not run coverage by default. Downstream app commit workflows run only `proteum refresh`, then targeted lint, typecheck, and test commands in parallel; framework-repo commit workflows skip this downstream app verification. Reserve the full `npm run check` gate for push workflows, explicit user requests, or when project-local instructions require the full gate. After implementing a new feature or changing existing feature behavior, update the relevant end-to-end coverage and run the cheapest trustworthy Playwright or browser verification for that behavior before finishing. For docs-only, wording-only, type-only, generated-output cleanup, or clearly local non-runtime refactors, skip Playwright unless the user explicitly asks for it or verification reveals a real issue.
 - Before finishing a task, stop every `proteum dev` session started during the task and confirm cleanup with `npx proteum dev list --json` or an explicit `npx proteum dev stop --session-file <path>`.
 - When you have finished your work, ask the user whether they want a commit message. After providing a commit message or after creating a commit, immediately follow it with this exact prompt and obey it:
   `Explain in short minimalistic and few bullet points what we changed in this thread, like you would do to your grandma. Start with a verb in the past.`
@@ -264,7 +264,7 @@ Verify at the correct layer:
 - Controller changes: exercise the generated client call or generated `/api/...` endpoint.
 - SSR changes: use the browser MCP to load the real page and inspect rendered HTML plus browser console.
 - Router or plugin changes: verify request context, auth, redirects, metrics, and validation on a running app.
-- New features or feature-behavior changes: use the cheapest trustworthy verification while iterating, use the browser MCP for browser-visible validation, then update and run the relevant end-to-end coverage. Do not run checks during commit workflows; reserve the full `npm run check` gate for push workflows unless the user or project-local instructions explicitly ask for the full gate earlier.
+- New features or feature-behavior changes: use the cheapest trustworthy verification while iterating, use the browser MCP for browser-visible validation, then update and run the relevant end-to-end coverage. During downstream app commit workflows, run only `proteum refresh`, then targeted lint, typecheck, and test commands in parallel; skip this verification for framework-repo commits and reserve the full `npm run check` gate for push workflows unless the user or project-local instructions explicitly ask for the full gate earlier.
 - Generated, connected, or ownership-ambiguous changes: start with MCP `workflow_start`, then `orient { projectId, query }` and `explain_summary { projectId, query }` only when more detail is needed; use `npx proteum orient <query>` and `npx proteum verify owner <query>` when MCP is unavailable or terminal evidence is required.
 - Browser-visible issues: use the browser MCP after request-level verification is insufficient. Use `npx proteum e2e --port <port> ...` only when automated end-to-end coverage or a Playwright suite is required.
 - Raw browser execution outside end-to-end suites: use the browser MCP only. Keep Playwright in `npx proteum e2e --port <port>` for targeted/full end-to-end suites.
@@ -311,7 +311,7 @@ Verify at the correct layer:
 - For read-only SQL diagnosis, use MCP `db_query` or `npx proteum db query "<sql>"`; only one capped `SELECT`, `SHOW`, or `EXPLAIN` statement is allowed.
 - Do not run `prisma *` yourself. If a schema change requires migration, ask the user to run `npx prisma migrate dev --config ./prisma.config.ts --name <migration name>` and wait for `continue`.
 - Do not run `git restore` or `git reset`.
-- Do not run write-mode git commands by default. The built-in exception is an exact `commit` reply, which allows `git add` and `git commit` in every affected repository or worktree touched during the whole conversation. Any other write-mode git action requires an explicit user request.
+- Do not run write-mode git commands by default. The built-in exception is an exact `commit` reply, which allows `git add` and `git commit` in every affected repository or worktree touched during the whole conversation after the applicable commit-time verification succeeds. For downstream apps, commit-time verification is limited to `proteum refresh`, then targeted lint, typecheck, and test commands in parallel. For the Proteum framework repository itself, skip this downstream app verification and use the framework repo `AGENTS.md` commit workflow. This exception does not allow coverage, full `npm run check`, repository `check:commit`, unrelated broad suites, or other checks unless the user explicitly requests them in the same message. Any other write-mode git action requires an explicit user request.
 
 ## Appendix
 

package/agents/project/tests/AGENTS.md

@@ -9,7 +9,7 @@ Diagnostics source of truth: root-level `diagnostics.md`.
 
 - Understand the real user flow and the main feature branches before writing tests.
 - Test the current controller/page runtime model, not legacy `@Route` or `api.fetch(...)` behavior.
-- For every production change, add or update focused unit tests and run the targeted test command that matches the changed behavior. When the repository defines `proteum.verify.config.ts`, use `npx proteum verify changed` first so changed test files, related source tests, and project-specific suites are selected consistently. Do not run whole-project coverage after every ordinary change by default. Do not run checks as part of a commit-only workflow; use `npm run check` as the full gate before push or when the user explicitly asks for it, and document any generated files, migrations, framework shims, unreachable defensive branches, or changes that cannot reasonably be unit-tested as explicit exceptions.
+- For every production change, add or update focused unit tests and run the targeted test command that matches the changed behavior. When the repository defines `proteum.verify.config.ts`, use `npx proteum verify changed` first so changed test files, related source tests, and project-specific suites are selected consistently. Do not run whole-project coverage after every ordinary change by default. Downstream app commit-only workflows run only `proteum refresh`, then targeted lint, typecheck, and test commands in parallel; framework-repo commit workflows skip this downstream app verification. Use `npm run check` as the full gate before push or when the user explicitly asks for it, and document any generated files, migrations, framework shims, unreachable defensive branches, or changes that cannot reasonably be unit-tested as explicit exceptions.
 - Verify routing, controllers, SSR, and router plugins against a running app when behavior depends on real request handling.
 - After implementing a new feature or changing existing feature behavior, update the end-to-end coverage for that behavior and run the full Playwright suite before finishing. Prefer `npx proteum e2e --port <port>` for Playwright runs so base URLs and auth tokens are passed through Proteum-managed child env instead of shell-leading environment assignments. Use a browser MCP repro against a running app during iteration when it is the fastest trustworthy loop.
 - Exercise real URLs, generated controller calls, or real browser flows instead of re-deriving framework internals in tests.

package/cli/commands/configure.ts

@@ -14,10 +14,12 @@ import { renderRows } from '../presentation/layout';
 import { isLikelyProteumAppRoot } from '../presentation/commands';
 import { renderStep, renderSuccess, renderTitle, renderWarning } from '../presentation/ink';
 import {
+    configureMonorepoProjectAgentInstructions,
     configureProjectAgentInstructions,
     findLikelyRepoRoot,
     isInsideDirectory,
     resolveCanonicalPath,
+    type TConfigureMonorepoProjectAgentInstructionsResult,
     type TConfigureProjectAgentInstructionsResult,
 } from '../utils/agents';
 
@@ -68,20 +70,22 @@ const promptMonorepoRoot = async ({
     return resolveCanonicalPath(String(response.value || defaultRoot || ''));
 };
 
-const promptBlockedOverwritePaths = async (blockedPaths: string[]) => {
-    if (blockedPaths.length === 0) return [];
+export const promptBlockedOverwritePaths = async (blockedPaths: string[]) => {
+    const uniqueBlockedPaths = [...new Set(blockedPaths)];
+
+    if (uniqueBlockedPaths.length === 0) return [];
 
     console.info(await renderWarning('Proteum found existing paths that block managed instruction updates.'));
     console.info(
         [
             'Choose whether to overwrite each path with a Proteum-managed instruction path:',
-            ...blockedPaths.map((entry) => `- ${entry}`),
+            ...uniqueBlockedPaths.map((entry) => `- ${entry}`),
         ].join('\n'),
     );
 
     const overwriteBlockedPaths: string[] = [];
 
-    for (const blockedPath of blockedPaths) {
+    for (const blockedPath of uniqueBlockedPaths) {
         const response = await prompts(
             {
                 type: 'confirm',
@@ -133,6 +137,12 @@ const renderConfigureResultSections = (result: TConfigureProjectAgentInstruction
     return sections;
 };
 
+const renderConfigureMonorepoResultSections = (result: TConfigureMonorepoProjectAgentInstructionsResult) =>
+    renderConfigureResultSections({
+        ...result,
+        appRoot: result.monorepoRoot,
+    });
+
 /*----------------------------------
 - COMMAND
 ----------------------------------*/
@@ -218,3 +228,52 @@ export const runConfigureAgentsWizard = async ({
 
     if (sections.length > 0) console.info(`\n${sections.join('\n\n')}`);
 };
+
+export const runConfigureAgentsMonorepoWizard = async ({
+    appRoots,
+    coreRoot = cli.paths.core.root,
+    monorepoRoot,
+}: {
+    appRoots: string[];
+    coreRoot?: string;
+    monorepoRoot: string;
+}) => {
+    if (appRoots.length === 0) throw new UsageError(`No Proteum app roots were found under ${monorepoRoot}.`);
+    for (const appRoot of appRoots) assertProteumAppRoot(appRoot);
+
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        throw new UsageError('`proteum configure agents` is interactive and requires a TTY.');
+    }
+
+    console.info(
+        [
+            await renderTitle('PROTEUM CONFIGURE AGENTS', 'Configure monorepo Proteum instruction files and Claude aliases.'),
+            renderRows([
+                { label: 'monorepo root', value: monorepoRoot === process.cwd() ? '.' : monorepoRoot },
+                { label: 'apps', value: String(appRoots.length) },
+            ]),
+        ].join('\n\n'),
+    );
+
+    const preview = configureMonorepoProjectAgentInstructions({
+        appRoots,
+        coreRoot,
+        dryRun: true,
+        monorepoRoot,
+    });
+    const overwriteBlockedPaths = await promptBlockedOverwritePaths(preview.blocked);
+
+    console.info(await renderStep('[1/1]', 'Writing monorepo root and app instruction files and Claude aliases.'));
+
+    const result = configureMonorepoProjectAgentInstructions({
+        appRoots,
+        coreRoot,
+        monorepoRoot,
+        overwriteBlockedPaths,
+    });
+    const sections = renderConfigureMonorepoResultSections(result);
+
+    console.info(await renderSuccess('Proteum-managed monorepo instruction files and Claude aliases are configured.'));
+
+    if (sections.length > 0) console.info(`\n${sections.join('\n\n')}`);
+};

package/cli/index.ts

@@ -9,6 +9,7 @@ import { renderCliOverview, renderCommandHelp, resolveCustomHelpRequest } from '
 import { renderCliWelcomeBanner } from './presentation/welcome';
 import { normalizeHelpArgv, normalizeLegacyArgv } from './runtime/argv';
 import { createCli, registeredCommands } from './runtime/commands';
+import { isMonorepoFanoutChild, maybeRunMonorepoCommand } from './runtime/monorepoCommands';
 
 const formatInvocation = (argv: string[]) => ['proteum', ...argv].join(' ').trim();
 
@@ -21,6 +22,7 @@ const shouldRenderSharedWelcomeBanner = ({
     argv: string[];
     helpRequestKind: 'none' | 'overview' | 'command';
 }) => {
+    if (isMonorepoFanoutChild()) return false;
     if (helpRequestKind !== 'none') return false;
     if (argv.length !== 1) return false;
 
@@ -32,27 +34,9 @@ const shouldRenderSharedWelcomeBanner = ({
 export const runCli = async (argv: string[] = process.argv.slice(2)) => {
     const normalizedArgv = normalizeHelpArgv(normalizeLegacyArgv(argv), proteumCommandNames);
     const version = String(cli.packageJson.version || '');
-    const proteumInstall = resolveFrameworkInstallInfo({
-        appRoot: cli.paths.appRoot,
-        framework: cli.paths.framework,
-    });
     const clipanion = createCli(version);
     const initAvailable = true;
     const helpRequest = resolveCustomHelpRequest(normalizedArgv);
-    const shouldRenderWelcomeBanner = shouldRenderSharedWelcomeBanner({
-        argv: normalizedArgv,
-        helpRequestKind: helpRequest.kind,
-    });
-
-    if (shouldRenderWelcomeBanner) {
-        process.stderr.write(
-            `${await renderCliWelcomeBanner({
-                command: formatInvocation(normalizedArgv),
-                installSummary: proteumInstall.summary,
-                version,
-            })}\n\n`,
-        );
-    }
 
     if (helpRequest.kind === 'overview') {
         process.stdout.write(
@@ -77,6 +61,28 @@ export const runCli = async (argv: string[] = process.argv.slice(2)) => {
         return;
     }
 
+    if (await maybeRunMonorepoCommand(normalizedArgv)) return;
+
+    const shouldRenderWelcomeBanner = shouldRenderSharedWelcomeBanner({
+        argv: normalizedArgv,
+        helpRequestKind: helpRequest.kind,
+    });
+
+    if (shouldRenderWelcomeBanner) {
+        const proteumInstall = resolveFrameworkInstallInfo({
+            appRoot: cli.paths.appRoot,
+            framework: cli.paths.framework,
+        });
+
+        process.stderr.write(
+            `${await renderCliWelcomeBanner({
+                command: formatInvocation(normalizedArgv),
+                installSummary: proteumInstall.summary,
+                version,
+            })}\n\n`,
+        );
+    }
+
     await clipanion.runExit(normalizedArgv, Cli.defaultContext);
 };
 

package/cli/mcp/router.ts

@@ -14,7 +14,12 @@ import { z } from 'zod/v4';
 import { buildContractsDoctorResponse } from '../../common/dev/contractsDoctor';
 import { buildDoctorResponse } from '../../common/dev/diagnostics';
 import { explainOwner } from '../../common/dev/inspection';
-import { compactWorkflowStartResponse, createMcpPayload, stringifyMcpPayload } from '../../common/dev/mcpPayloads';
+import {
+    compactWorkflowStartResponse,
+    createMcpPayload,
+    stringifyMcpPayload,
+    type TProteumMcpNextAction,
+} from '../../common/dev/mcpPayloads';
 import { readProteumManifest } from '../compiler/common/proteumManifest';
 import {
     createMachineMcpDaemonRecord,
@@ -42,6 +47,7 @@ import {
     createWorktreeBootstrapMcpBlockResponse,
     getWorktreeBootstrapStatus,
 } from '../runtime/worktreeBootstrap';
+import { buildFreshCopyPreflight } from '../runtime/freshCopyPreflight';
 
 type TDevMcpClient = {
     callTool: (input: { arguments?: Record<string, unknown>; name: string }) => Promise<CallToolResult>;
@@ -102,6 +108,25 @@ const errorToolResult = (summary: string, data: Record<string, unknown> = {}) =>
         true,
     );
 
+const dedupeNextActions = (actions: TProteumMcpNextAction[]) => {
+    const seen = new Set<string>();
+    const output: TProteumMcpNextAction[] = [];
+
+    for (const action of actions) {
+        const key = JSON.stringify({
+            command: action.command,
+            label: action.label,
+            tool: action.tool,
+            toolArgs: action.toolArgs,
+        });
+        if (seen.has(key)) continue;
+        seen.add(key);
+        output.push(action);
+    }
+
+    return output;
+};
+
 const compactProject = (record: TMachineDevSessionRecord) => ({
     projectId: record.projectId,
     appRoot: record.appRoot,
@@ -440,7 +465,7 @@ export const createProteumMachineMcpServer = ({ createDevMcpClient, version }: T
         }
     };
 
-    const createOfflineWorkflowStartResult = (offline: TOfflineProject, input: Record<string, unknown>) => {
+    const createOfflineWorkflowStartResult = async (offline: TOfflineProject, input: Record<string, unknown>) => {
         const bootstrapStatus = getWorktreeBootstrapStatus({ appRoot: offline.appRoot, proteumVersion: version });
         if (bootstrapStatus.blocking) return jsonToolResult(createWorktreeBootstrapMcpBlockResponse(bootstrapStatus, offline), true);
 
@@ -448,25 +473,30 @@ export const createProteumMachineMcpServer = ({ createDevMcpClient, version }: T
         try {
             manifest = readProteumManifest(offline.appRoot);
         } catch (error) {
+            const preflight = await buildFreshCopyPreflight({
+                appRoot: offline.appRoot,
+                baseRoot: offline.appRoot,
+            });
+
             return jsonToolResult(
                 createMcpPayload({
                     summary: `Matched offline Proteum app ${offline.appRoot}, but no readable manifest is available.`,
                     data: {
                         project: offline,
+                        readiness: preflight.readiness,
+                        worktreeBootstrap: compactWorktreeBootstrapStatus(bootstrapStatus),
                         error: error instanceof Error ? error.message : String(error),
                     },
-                    nextActions: [
-                        offline.nextAction,
-                        {
-                            label: 'Refresh Manifest',
-                            command: 'npx proteum refresh',
-                            reason: 'Generate the compact manifest before owner, route, or instruction routing reads.',
-                        },
-                    ],
+                    nextActions: dedupeNextActions([...preflight.nextActions, offline.nextAction]),
                 }),
             );
         }
 
+        const preflight = await buildFreshCopyPreflight({
+            appRoot: offline.appRoot,
+            baseRoot: offline.appRoot,
+            manifest,
+        });
         const doctor = buildDoctorResponse(manifest);
         const contracts = buildContractsDoctorResponse(manifest);
         const route = typeof input.route === 'string' ? input.route : undefined;
@@ -495,15 +525,17 @@ export const createProteumMachineMcpServer = ({ createDevMcpClient, version }: T
             ...payload,
             data: {
                 project: offline,
+                readiness: preflight.readiness,
                 worktreeBootstrap: compactWorktreeBootstrapStatus(bootstrapStatus),
                 ...payload.data,
             },
-            nextActions: [
+            nextActions: dedupeNextActions([
+                ...preflight.nextActions,
                 offline.nextAction,
                 ...(Array.isArray(payload.nextActions)
                     ? payload.nextActions.filter((action: { label?: unknown }) => action.label !== 'Start Dev')
                     : []),
-            ],
+            ]),
         });
     };
 
@@ -528,7 +560,7 @@ export const createProteumMachineMcpServer = ({ createDevMcpClient, version }: T
         const selectedMatch = matches[0];
         const record = selectedMatch.record;
 
-        if (!record && selectedMatch.offline) return createOfflineWorkflowStartResult(selectedMatch.offline, input);
+        if (!record && selectedMatch.offline) return await createOfflineWorkflowStartResult(selectedMatch.offline, input);
         if (!record) {
             return errorToolResult('Could not resolve a live Proteum project for workflow_start. Call projects_list or project_resolve.', {
                 matches: matches.map((match) => match.project),
@@ -550,7 +582,20 @@ export const createProteumMachineMcpServer = ({ createDevMcpClient, version }: T
             if (result.content[0]?.type !== 'text') return result;
 
             const payload = JSON.parse(result.content[0].text);
-            const routedNextActions = Array.isArray(payload.nextActions)
+            let preflight;
+            try {
+                preflight = await buildFreshCopyPreflight({
+                    appRoot: record.appRoot,
+                    baseRoot: record.appRoot,
+                    manifest: readProteumManifest(record.appRoot),
+                });
+            } catch (_error) {
+                preflight = await buildFreshCopyPreflight({
+                    appRoot: record.appRoot,
+                    baseRoot: record.appRoot,
+                });
+            }
+            const routedNextActions: TProteumMcpNextAction[] | undefined = Array.isArray(payload.nextActions)
                 ? payload.nextActions.map((action: Record<string, unknown>) =>
                       action.tool && typeof action.tool === 'string'
                           ? {
@@ -568,10 +613,11 @@ export const createProteumMachineMcpServer = ({ createDevMcpClient, version }: T
                 ...payload,
                 data: {
                     project: compactProject(record),
+                    readiness: preflight.readiness,
                     worktreeBootstrap: compactWorktreeBootstrapStatus(bootstrapStatus),
                     ...payload.data,
                 },
-                ...(routedNextActions && routedNextActions.length > 0 ? { nextActions: routedNextActions } : {}),
+                nextActions: dedupeNextActions([...preflight.nextActions, ...(routedNextActions || [])]),
             });
         } catch (error) {
             await closeClient(record);