proteum 2.5.2 → 2.5.4

package/AGENTS.md

@@ -65,7 +65,7 @@ npx prisma migrate dev --config ./prisma.config.ts --name <migration name>
 - Keep the developer-facing contract synchronized when framework work changes CLI commands, profiler capabilities, or the `proteum dev` banner. Update the live surfaces together in the same pass: CLI command/help definitions, profiler panels and dev-only endpoints, banner text/examples, and the most relevant agent docs that describe them, especially `AGENTS.md`, `agents/project/AGENTS.md`, `agents/project/root/AGENTS.md`, `agents/project/app-root/AGENTS.md`, `agents/project/diagnostics.md`, and any narrower `agents/project/**/AGENTS.md` file that mentions the changed workflow.
 - Proteum MCP contract: `proteum mcp` is the machine-scope router agents register once, and `proteum dev` exposes each app runtime at `/__proteum/mcp`. `proteum dev` ensures one managed machine MCP daemon is running; do not start a second managed daemon. Agents should start with MCP `workflow_start` using `cwd` or a known `projectId`; ambiguous routing or offline app candidates use `project_resolve { cwd }`, and follow-up live app tools require the returned `projectId`. Dev-hosted app tools are already rooted to their own runtime. Keep MCP tools/resources compact, typed, capped, paginated for full trace detail, and read-only unless a future task explicitly expands the mutation contract. The database diagnostic exception is still read-only: MCP `db_query` and CLI `proteum db query` allow one capped `SELECT`, `SHOW`, or `EXPLAIN` statement only and return rows plus elapsed milliseconds. MCP payloads are compact single-line `proteum-mcp-v1` JSON, not pretty-printed human output. Do not implement MCP tools as thin CLI process wrappers when the data is available through manifest readers, tracked sessions, or dev runtime registries.
 - Keep the same-system trace contract explicit when request instrumentation changes: `TRACE_*` controls the retained dev trace store plus the trace/perf CLI, dev-only HTTP endpoints, and bottom profiler, while `ENABLE_PROFILER` enables the reduced request-local `request.profiling` snapshot and `request.finished` hook payload without retaining finished requests globally unless dev trace is also enabled.
-- Current CLI banner contract: only the bare `proteum build` and bare `proteum dev` commands print the welcome banner and include the active Proteum installation method. Any extra argument or option skips the welcome banner. Terminal `proteum mcp` may print a compact central MCP ready banner when it starts or reuses the managed daemon. Only `proteum dev` clears the interactive terminal before rendering, exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys in its session UI, and reports connected app names plus successful connected `/ping` checks in the ready banner. Every `proteum dev` start ensures tracked instruction files contain the current managed `# Proteum Instructions` section before the dev loop begins.
+- Current CLI banner contract: only the bare `proteum build` and bare `proteum dev` commands print the welcome banner and include the active Proteum installation method. Any extra argument or option skips the welcome banner. Terminal `proteum mcp` may print a compact central MCP ready banner when it starts or reuses the managed daemon. Only `proteum dev` clears the interactive terminal before rendering, exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys in its session UI, and reports connected app names plus successful connected `/ping` checks in the ready banner. Every `proteum dev` start ensures tracked instruction files contain the current managed `# Proteum Instructions` section and `CLAUDE.md` symlinks point to sibling `AGENTS.md` files before the dev loop begins.
 - Keep core changes aligned with the explicit controller/page architecture in `agents/project/root/AGENTS.md` and its standalone composition in `agents/project/AGENTS.md`.
 - Prefer removing framework magic when the same result can be expressed with explicit contracts, generated code, or typed context.
 - Apply the pruning rules from `agents/project/optimizations.md`, especially for webpack plugins, Babel plugins, aliases, helpers, runtime services, and npm packages that are not meaningfully used by both apps.

package/README.md

@@ -403,7 +403,7 @@ Proteum ships with a compact CLI focused on the real app lifecycle:
 | `proteum e2e` | Run Playwright with Proteum-managed `E2E_*` values instead of shell-leading env assignments |
 | `proteum verify` | Validate targeted changed-file checks, focused owner/request/browser workflows, or the full framework reference-app pass |
 | `proteum init` | Scaffold a new Proteum app with built-in deterministic templates |
-| `proteum configure agents` | Interactively configure tracked Proteum instruction files for standalone or monorepo apps |
+| `proteum configure agents` | Interactively configure tracked Proteum instruction files and Claude aliases |
 | `proteum create` | Scaffold a page, controller, command, route, or root service inside an app |
 | `proteum worktree` | Create or initialize Codex worktrees with a machine-readable bootstrap marker |
 
@@ -419,7 +419,7 @@ proteum build --prod --analyze
 proteum build --prod --analyze --analyze-serve --analyze-port auto
 ```
 
-Only the bare `proteum build` and bare `proteum dev` commands print the welcome banner and include the active Proteum installation method. Any extra argument or option skips the banner. `proteum dev` is the only command that clears the interactive terminal before rendering its live session UI, exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys, and prints connected app names plus successful connected `/ping` checks in the server-ready banner. Every `proteum dev` start ensures tracked Proteum instruction files contain the current managed `# Proteum Instructions` section before the dev loop begins.
+Only the bare `proteum build` and bare `proteum dev` commands print the welcome banner and include the active Proteum installation method. Any extra argument or option skips the banner. `proteum dev` is the only command that clears the interactive terminal before rendering its live session UI, exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys, and prints connected app names plus successful connected `/ping` checks in the server-ready banner. Every `proteum dev` start ensures tracked Proteum instruction files contain the current managed `# Proteum Instructions` section and `CLAUDE.md` symlinks point to sibling `AGENTS.md` files before the dev loop begins.
 
 Useful inspection commands:
 
@@ -467,11 +467,11 @@ proteum create controller Founder/projects --method list
 proteum create service Conversion/Plans
 ```
 
-`proteum configure agents` writes a compact managed `# Proteum Instructions` router plus the task-specific instruction files that router points to. Standalone mode writes root documents into the app root; monorepo mode writes shared root documents such as `AGENTS.md`, `DOCUMENTATION.md`, `CODING_STYLE.md`, `diagnostics.md`, and `optimizations.md` into the chosen monorepo root and keeps only app-local instruction files in the Proteum app root. It preserves content outside managed sections and asks before replacing directories or foreign symlinks. If you decline, that path is left untouched.
+`proteum configure agents` writes a compact managed `# Proteum Instructions` router plus the task-specific instruction files that router points to. Standalone mode writes root documents into the app root; monorepo mode writes shared root documents such as `AGENTS.md`, `DOCUMENTATION.md`, `CODING_STYLE.md`, `diagnostics.md`, and `optimizations.md` into the chosen monorepo root and keeps only app-local instruction files in the Proteum app root. For each generated `AGENTS.md`, it creates a sibling `CLAUDE.md` symlink pointing to `AGENTS.md`. It preserves content outside managed sections and asks before replacing directories, foreign symlinks, or unrelated files. If you decline, that path is left untouched.
 
 Every `proteum dev` start runs the same idempotent instruction check. It updates missing or stale managed sections automatically and prompts only when a blocked path would need to be replaced.
 
-`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. `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 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).
 

package/agents/project/AGENTS.md

@@ -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. Before staging or committing, run the repository's non-coverage commit gate when it defines one, such as `npm run check:commit`; otherwise run targeted lint, typecheck, and test commands. Report any blocker instead of committing through a failed commit gate. 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. 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.
   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.`
 
@@ -74,13 +74,13 @@ Managed compact root routers must use trigger -> canonical instruction file refe
 - If the current app depends on local `file:` connected projects, boot every connected producer app too, each with its own task-scoped session file and free port, and run every one of those `proteum dev` processes with elevated permissions outside the sandbox before starting or verifying the consumer app.
 - During `npx proteum dev`, the app exposes the read-only Proteum MCP runtime endpoint at `/__proteum/mcp`; use it for repeated agent reads instead of spawning equivalent diagnostics commands. For route/page/controller ownership, prefer MCP `workflow_start`, `route_candidates { projectId, query }`, or `explain_summary { projectId, query }` over broad `npx proteum explain --routes --controllers --full` dumps.
 - For browser validation, use the browser MCP against the running app. Keep Playwright inside `npx proteum e2e --port <port>` for targeted/full end-to-end suites. Bootstrap protected browser MCP state with `npx proteum session`; bootstrap protected E2E runs with `npx proteum e2e --session-email <email> --session-role <role>`.
-- Current CLI banner contract: only the bare `proteum build` and bare `proteum dev` commands print the welcome banner and include the active Proteum installation method. Any extra argument or option skips the welcome banner. Terminal `proteum mcp` may print a compact central MCP ready banner when it starts or reuses the managed daemon. Only `proteum dev` clears the interactive terminal before rendering, exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys in its session UI, and reports connected app names plus successful connected `/ping` checks in the ready banner. Every `proteum dev` start ensures tracked instruction files contain the current managed `# Proteum Instructions` section before the dev loop begins.
+- Current CLI banner contract: only the bare `proteum build` and bare `proteum dev` commands print the welcome banner and include the active Proteum installation method. Any extra argument or option skips the welcome banner. Terminal `proteum mcp` may print a compact central MCP ready banner when it starts or reuses the managed daemon. Only `proteum dev` clears the interactive terminal before rendering, exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys in its session UI, and reports connected app names plus successful connected `/ping` checks in the ready banner. Every `proteum dev` start ensures tracked instruction files contain the current managed `# Proteum Instructions` section and `CLAUDE.md` symlinks point to sibling `AGENTS.md` files before the dev loop begins.
 
 ### Before Finishing
 
 - 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. Reserve the non-coverage commit gate for commit workflows, and 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. 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.
 - 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. Save the non-coverage commit gate for commit workflows and 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. 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.
 - 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 after the repository's non-coverage commit gate passes when it defines one, such as `npm run check:commit`. 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. 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.
 
 ## 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 coverage for commit-only workflows by default. 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; 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.
 
 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. Run the repository's non-coverage commit gate before committing, and 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. 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.
 
 ## Type safety
 

package/agents/project/diagnostics.md

@@ -18,7 +18,7 @@ This file is the canonical source of truth for diagnostics, temporary instrument
 
 - For long-lived dev reproductions, always request elevated permissions and run `npx proteum dev` outside the sandbox. Use an explicit task/thread-scoped session file, inspect `npx proteum runtime status` first, then use its exact next action so occupied router/HMR ports and untracked same-app runtimes are handled without page-body probes. After the server is ready, print the live server URL as a clickable Markdown link.
 - Use `--replace-existing` only when restarting the exact session file started by the current thread/task. Never replace another live session that belongs to a user, another thread, or an unknown owner.
-- Only the bare `npx proteum build` and bare `npx proteum dev` commands print the welcome banner and active Proteum installation method. Any extra argument or option skips the welcome banner. Terminal `npx proteum mcp` may print a compact central MCP ready banner when it starts or reuses the managed daemon. Only `npx proteum dev` clears the interactive terminal before rendering and reports connected app names plus successful connected `/ping` checks in the ready banner; keep that in mind when capturing or comparing command logs during diagnosis. Every `npx proteum dev` start ensures tracked instruction files contain the current managed `# Proteum Instructions` section before the dev loop begins.
+- Only the bare `npx proteum build` and bare `npx proteum dev` commands print the welcome banner and active Proteum installation method. Any extra argument or option skips the welcome banner. Terminal `npx proteum mcp` may print a compact central MCP ready banner when it starts or reuses the managed daemon. Only `npx proteum dev` clears the interactive terminal before rendering and reports connected app names plus successful connected `/ping` checks in the ready banner; keep that in mind when capturing or comparing command logs during diagnosis. Every `npx proteum dev` start ensures tracked instruction files contain the current managed `# Proteum Instructions` section and `CLAUDE.md` symlinks point to sibling `AGENTS.md` files before the dev loop begins.
 - During `npx proteum dev`, the running app exposes the read-only Proteum MCP transport at `/__proteum/mcp`. Use it for runtime-adjacent agent reads instead of repeatedly spawning equivalent CLI diagnostics.
 - If machine MCP routing fails, run `npx proteum mcp status` and `npx proteum runtime status` from the intended app root. If no live session exists, use the exact MCP offline or runtime-status next action 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 start a second dev server in the same worktree, and do not start a second managed MCP daemon. Do not run diagnose, trace, or perf reads while runtime health is unreachable. Then retry MCP `workflow_start` and use the returned `projectId`.
 - For ownership or repo discovery questions, start with MCP `workflow_start`; use MCP `route_candidates { projectId, query }`, MCP `orient { projectId, query }`, and MCP `explain_summary { projectId, query }` only when the bootstrap owner summary is insufficient. Use `npx proteum orient <query>` or `npx proteum explain owner <query>` only when MCP is unavailable or terminal evidence is required.
@@ -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. Run the repository's non-coverage commit gate before committing, and 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. 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.
 - 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

@@ -59,14 +59,14 @@ Managed compact root routers must use trigger -> canonical instruction file refe
 - If the current app depends on local `file:` connected projects, boot every connected producer app too, each with its own task-scoped session file and free port, and run every one of those `proteum dev` processes with elevated permissions outside the sandbox before starting or verifying the consumer app.
 - During `npx proteum dev`, the app exposes the read-only Proteum MCP runtime endpoint at `/__proteum/mcp`; use it for repeated agent reads instead of spawning equivalent diagnostics commands. For route/page/controller ownership, prefer MCP `workflow_start`, `route_candidates { projectId, query }`, or `explain_summary { projectId, query }` over broad `npx proteum explain --routes --controllers --full` dumps.
 - For browser validation, use the browser MCP against the running app. Keep Playwright inside `npx proteum e2e --port <port>` for targeted/full end-to-end suites. Bootstrap protected browser MCP state with `npx proteum session`; bootstrap protected E2E runs with `npx proteum e2e --session-email <email> --session-role <role>`.
-- Current CLI banner contract: only the bare `proteum build` and bare `proteum dev` commands print the welcome banner and include the active Proteum installation method. Any extra argument or option skips the welcome banner. Terminal `proteum mcp` may print a compact central MCP ready banner when it starts or reuses the managed daemon. Only `proteum dev` clears the interactive terminal before rendering, exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys in its session UI, and reports connected app names plus successful connected `/ping` checks in the ready banner. Every `proteum dev` start ensures tracked instruction files contain the current managed `# Proteum Instructions` section before the dev loop begins.
+- Current CLI banner contract: only the bare `proteum build` and bare `proteum dev` commands print the welcome banner and include the active Proteum installation method. Any extra argument or option skips the welcome banner. Terminal `proteum mcp` may print a compact central MCP ready banner when it starts or reuses the managed daemon. Only `proteum dev` clears the interactive terminal before rendering, exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys in its session UI, and reports connected app names plus successful connected `/ping` checks in the ready banner. Every `proteum dev` start ensures tracked instruction files contain the current managed `# Proteum Instructions` section and `CLAUDE.md` symlinks point to sibling `AGENTS.md` files before the dev loop begins.
 
 ### Before Finishing
 
 - 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 coverage for commit-only workflows by default. 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. Reserve the non-coverage commit gate for commit workflows, and 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; 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.
 - 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. Save the non-coverage commit gate for commit workflows and 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. 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.
 - 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.

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. Use the repository's non-coverage commit gate before commit, and 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. 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.
 - 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

@@ -74,7 +74,7 @@ const promptBlockedOverwritePaths = async (blockedPaths: string[]) => {
     console.info(await renderWarning('Proteum found existing paths that block managed instruction updates.'));
     console.info(
         [
-            'Choose whether to overwrite each path with a tracked Proteum instruction file:',
+            'Choose whether to overwrite each path with a Proteum-managed instruction path:',
             ...blockedPaths.map((entry) => `- ${entry}`),
         ].join('\n'),
     );
@@ -163,7 +163,7 @@ export const runConfigureAgentsWizard = async ({
             : undefined;
     console.info(
         [
-            await renderTitle('PROTEUM CONFIGURE AGENTS', 'Configure tracked Proteum instruction files.'),
+            await renderTitle('PROTEUM CONFIGURE AGENTS', 'Configure tracked Proteum instruction files and Claude aliases.'),
             renderRows([{ label: 'app', value: appRoot === process.cwd() ? '.' : appRoot }]),
         ].join('\n\n'),
     );
@@ -201,8 +201,8 @@ export const runConfigureAgentsWizard = async ({
         await renderStep(
             '[1/1]',
             isMonorepo
-                ? `Writing monorepo-aware instruction files using ${monorepoRoot}.`
-                : 'Writing standalone instruction files.',
+                ? `Writing monorepo-aware instruction files and Claude aliases using ${monorepoRoot}.`
+                : 'Writing standalone instruction files and Claude aliases.',
         ),
     );
 
@@ -214,7 +214,7 @@ export const runConfigureAgentsWizard = async ({
     });
     const sections = renderConfigureResultSections(result);
 
-    console.info(await renderSuccess('Proteum-managed instruction files are configured.'));
+    console.info(await renderSuccess('Proteum-managed instruction files and Claude aliases are configured.'));
 
     if (sections.length > 0) console.info(`\n${sections.join('\n\n')}`);
 };

package/cli/commands/dev.ts

@@ -153,7 +153,7 @@ const promptBlockedAgentInstructionOverwrites = async (blockedPaths: string[]) =
     if (cli.args.json === true || !process.stdin.isTTY || !process.stdout.isTTY) {
         throw new UsageError(
             [
-                'Proteum could not update managed instruction files because existing paths are blocked:',
+                'Proteum could not update managed instruction paths because existing paths are blocked:',
                 ...blockedPaths.map((entry) => `- ${entry}`),
                 'Run `proteum configure agents` in an interactive terminal to choose which paths can be replaced.',
             ].join('\n'),
@@ -163,7 +163,7 @@ const promptBlockedAgentInstructionOverwrites = async (blockedPaths: string[]) =
     console.info(await renderWarning('Proteum found existing paths that block managed instruction updates.'));
     console.info(
         [
-            'Choose whether to overwrite each blocked path with a tracked Proteum instruction file:',
+            'Choose whether to overwrite each blocked path with a Proteum-managed instruction path:',
             ...blockedPaths.map((entry) => `- ${entry}`),
         ].join('\n'),
     );
@@ -212,7 +212,7 @@ const ensureProjectAgentInstructions = async () => {
 
     throw new UsageError(
         [
-            'Proteum could not update all managed instruction files because these paths were left blocked:',
+            'Proteum could not update all managed instruction paths because these paths were left blocked:',
             ...result.blocked.map((entry) => `- ${entry}`),
         ].join('\n'),
     );

package/cli/presentation/commands.ts

@@ -116,7 +116,7 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
     configure: {
         name: 'configure',
         category: 'Project scaffolding',
-        summary: 'Interactively configure tracked Proteum instruction files for a standalone app or monorepo app root.',
+        summary: 'Interactively configure tracked Proteum instruction files and Claude aliases for an app.',
         usage: 'proteum configure agents',
         bestFor:
             'Creating or switching the tracked instruction layout intentionally while keeping Proteum-owned instructions embedded in managed sections.',
@@ -128,8 +128,9 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         ],
         notes: [
             'This command is interactive. It asks whether the current Proteum app belongs to a monorepo and, if so, which ancestor path should receive the reusable root instruction files.',
-            'Standalone mode writes tracked instruction files into the current Proteum app root.',
+            'Standalone mode writes tracked instruction files into the current Proteum app root and creates `CLAUDE.md` symlinks beside each `AGENTS.md`.',
             'Monorepo mode writes reusable root documents such as `AGENTS.md`, `DOCUMENTATION.md`, `CODING_STYLE.md`, `diagnostics.md`, and `optimizations.md` into the chosen monorepo root, then writes only app-root and area instruction files into the current Proteum app root.',
+            'Every generated `CLAUDE.md` is a sibling symlink pointing to `AGENTS.md`.',
             'Every managed instruction file contains a `# Proteum Instructions` section with the full embedded Proteum project instruction corpus.',
             'Existing content outside `# Proteum Instructions` is preserved. Directories and foreign symlinks are replaced only after confirmation.',
         ],
@@ -165,6 +166,7 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         notes: [
             'Bootstrap writes `.proteum/worktree-bootstrap.json` with hashes, step timestamps, dependency status, runtime status, and Proteum version.',
             'When `.env` is missing, `--source` is required and must point to an app root with a readable `.env`.',
+            'For monorepos with root tooling, bootstrap also ensures the workspace-root `.env` exists from the source root or source app env.',
             'Guarded commands block inside `/.codex/worktrees/` until bootstrap is complete or explicitly bypassed with `PROTEUM_ALLOW_UNBOOTSTRAPPED_WORKTREE=1`.',
             '`worktree create` preserves the source app root path relative to the source repository root, so monorepo app roots are bootstrapped in the matching target location.',
         ],

package/cli/presentation/help.ts

@@ -139,7 +139,7 @@ export const renderCliOverview = async ({
                     indent: '  ',
                     nextIndent: '  ',
                 }),
-                wrapText('Before the dev loop starts, `proteum dev` ensures tracked instruction files contain the current managed `# Proteum Instructions` section.', {
+                wrapText('Before the dev loop starts, `proteum dev` ensures tracked instruction files contain the current managed `# Proteum Instructions` section and `CLAUDE.md` symlinks point to sibling `AGENTS.md` files.', {
                     indent: '  ',
                     nextIndent: '  ',
                 }),

package/cli/runtime/commands.ts

@@ -175,7 +175,7 @@ class WorktreeCommand extends ProteumCommand {
 
     public static usage = buildUsage('worktree');
 
-    public source = Option.String('--source', { description: 'Source Proteum app root used for .env copy and worktree creation.' });
+    public source = Option.String('--source', { description: 'Source Proteum app root used for app/root .env copy and worktree creation.' });
     public branch = Option.String('--branch', { description: 'Branch name created by `worktree create`.' });
     public base = Option.String('--base', { description: 'Base ref used by `worktree create`.' });
     public refresh = Option.Boolean('--refresh', false, { description: 'Refresh an existing stale bootstrap marker.' });

package/cli/runtime/worktreeBootstrap.ts

@@ -23,6 +23,13 @@ export type TWorktreeBootstrapMarker = {
         copied: boolean;
         copiedAt?: string;
         present: boolean;
+        root?: {
+            copied: boolean;
+            copiedAt?: string;
+            filepath: string;
+            present: boolean;
+            source?: string;
+        };
         source?: string;
     };
     packageLockHash?: string;
@@ -84,6 +91,11 @@ type TWorktreeBootstrapInputs = {
     packageLockHash?: string;
     proteumConfigHash?: string;
     proteumVersion: string;
+    rootEnv?: {
+        filepath: string;
+        present: boolean;
+        required: boolean;
+    };
 };
 
 type TRunCaptureResult = {
@@ -159,6 +171,32 @@ const findVisibleDirectory = (startPath: string, directoryName: string) => {
     }
 };
 
+const readJsonFile = (filepath: string) => {
+    try {
+        return fs.readJSONSync(filepath) as Record<string, unknown>;
+    } catch {
+        return {};
+    }
+};
+
+const hasWorkspaceRootTooling = (workspaceRoot: string) => {
+    if (fs.existsSync(path.join(workspaceRoot, 'prisma.config.ts'))) return true;
+
+    const packageJson = readJsonFile(path.join(workspaceRoot, 'package.json'));
+    return Array.isArray(packageJson.workspaces);
+};
+
+const resolveWorkspaceRootEnv = (appRoot: string) => {
+    const packageLockFilepath = findNearestExistingPath(appRoot, 'package-lock.json');
+    if (!packageLockFilepath) return undefined;
+
+    const workspaceRoot = path.dirname(packageLockFilepath);
+    if (workspaceRoot === normalizePath(appRoot)) return undefined;
+    if (!hasWorkspaceRootTooling(workspaceRoot)) return undefined;
+
+    return path.join(workspaceRoot, '.env');
+};
+
 const hashFile = (filepath: string | undefined) => {
     if (!filepath || !fs.existsSync(filepath)) return undefined;
 
@@ -177,6 +215,7 @@ const readMarker = (markerFilepath: string) => {
 
 const readInputs = (appRoot: string, proteumVersion: string): TWorktreeBootstrapInputs => {
     const packageLockFilepath = findNearestExistingPath(appRoot, 'package-lock.json');
+    const rootEnvFilepath = resolveWorkspaceRootEnv(appRoot);
 
     return {
         agentsHash: hashFile(path.join(appRoot, 'AGENTS.md')),
@@ -186,6 +225,13 @@ const readInputs = (appRoot: string, proteumVersion: string): TWorktreeBootstrap
         packageLockHash: hashFile(packageLockFilepath),
         proteumConfigHash: hashFile(path.join(appRoot, 'proteum.config.ts')),
         proteumVersion,
+        rootEnv: rootEnvFilepath
+            ? {
+                  filepath: rootEnvFilepath,
+                  present: fs.existsSync(rootEnvFilepath),
+                  required: true,
+              }
+            : undefined,
     };
 };
 
@@ -217,6 +263,8 @@ const collectStaleReasons = ({
     if (marker.agentsHash !== inputs.agentsHash)
         reasons.push({ code: 'worktree-bootstrap/agents-changed', message: 'AGENTS.md changed since bootstrap.' });
     if (!inputs.envPresent) reasons.push({ code: 'worktree-bootstrap/env-missing', message: '.env is missing.' });
+    if (inputs.rootEnv?.required && !inputs.rootEnv.present)
+        reasons.push({ code: 'worktree-bootstrap/root-env-missing', message: 'Workspace root .env is missing.' });
     if (!inputs.manifestPresent)
         reasons.push({ code: 'worktree-bootstrap/manifest-missing', message: '.proteum/manifest.json is missing.' });
     if (!inputs.nodeModulesPresent && !dependenciesWereIntentionallySkipped(marker, inputs))
@@ -309,18 +357,63 @@ const resolveDependencyAction = ({
     return 'up-to-date';
 };
 
+const resolveSourceRootEnv = (source: string) => {
+    const sourceWorkspaceRootEnv = resolveWorkspaceRootEnv(source);
+    if (sourceWorkspaceRootEnv && fs.existsSync(sourceWorkspaceRootEnv)) return sourceWorkspaceRootEnv;
+
+    const sourceEnvFilepath = path.join(path.resolve(source), '.env');
+    return fs.existsSync(sourceEnvFilepath) ? sourceEnvFilepath : undefined;
+};
+
 const requireSourceEnvWhenNeeded = ({ appRoot, source }: { appRoot: string; source?: string }) => {
     const envFilepath = path.join(appRoot, '.env');
-    if (fs.existsSync(envFilepath)) return { copied: false, present: true, source: undefined };
+    const rootEnvFilepath = resolveWorkspaceRootEnv(appRoot);
+    let copied = false;
+    let copiedAt: string | undefined;
+    let sourceForEnv: string | undefined;
 
-    if (!source) throw new Error('This worktree is missing .env. Pass --source <app-root> with a readable source .env.');
+    if (!fs.existsSync(envFilepath)) {
+        if (!source) throw new Error('This worktree is missing .env. Pass --source <app-root> with a readable source .env.');
 
-    const sourceEnvFilepath = path.join(path.resolve(source), '.env');
-    if (!fs.existsSync(sourceEnvFilepath)) throw new Error(`Source .env does not exist: ${sourceEnvFilepath}`);
+        const sourceEnvFilepath = path.join(path.resolve(source), '.env');
+        if (!fs.existsSync(sourceEnvFilepath)) throw new Error(`Source .env does not exist: ${sourceEnvFilepath}`);
 
-    fs.copyFileSync(sourceEnvFilepath, envFilepath);
+        fs.copyFileSync(sourceEnvFilepath, envFilepath);
+        copied = true;
+        copiedAt = nowIso();
+        sourceForEnv = path.resolve(source);
+    }
 
-    return { copied: true, copiedAt: nowIso(), present: true, source: path.resolve(source) };
+    const root: TWorktreeBootstrapMarker['env']['root'] | undefined = rootEnvFilepath
+        ? {
+              copied: false,
+              filepath: rootEnvFilepath,
+              present: fs.existsSync(rootEnvFilepath),
+          }
+        : undefined;
+
+    if (root && !root.present) {
+        if (!source) throw new Error('This worktree is missing workspace root .env. Pass --source <app-root> with a readable source .env.');
+
+        const sourceRootEnvFilepath = resolveSourceRootEnv(source);
+        if (!sourceRootEnvFilepath) {
+            throw new Error(`Source workspace root .env does not exist and source app .env is missing: ${path.resolve(source)}`);
+        }
+
+        fs.copyFileSync(sourceRootEnvFilepath, root.filepath);
+        root.copied = true;
+        root.copiedAt = nowIso();
+        root.present = true;
+        root.source = sourceRootEnvFilepath;
+    }
+
+    return {
+        copied,
+        ...(copiedAt ? { copiedAt } : {}),
+        present: fs.existsSync(envFilepath),
+        ...(root ? { root } : {}),
+        ...(sourceForEnv ? { source: sourceForEnv } : {}),
+    };
 };
 
 const writeMarker = (appRoot: string, marker: TWorktreeBootstrapMarker) => {

package/cli/utils/agents.ts

@@ -60,6 +60,9 @@ const managedInstructionSectionHeader = '# Proteum Instructions';
 const managedInstructionSectionStart = '<!-- proteum-instructions:start -->';
 const managedInstructionSectionEnd = '<!-- proteum-instructions:end -->';
 const managedInstructionSectionIntro = 'This section is managed by `proteum configure agents`.';
+const agentInstructionFilename = 'AGENTS.md';
+const claudeInstructionFilename = 'CLAUDE.md';
+const claudeInstructionPointerContent = `@${agentInstructionFilename}`;
 
 const sharedRootDocumentInstructionDefinitions: TAgentInstructionDefinition[] = [
     { projectPath: 'DOCUMENTATION.md', content: 'source' },
@@ -243,6 +246,45 @@ function getRootAgentInstructionDefinitions() {
     return monorepoRootAgentInstructionDefinitions.map((instructionDefinition) => ({ ...instructionDefinition }));
 }
 
+function createEmptyInstructionResult(): TEnsureInstructionFilesResult {
+    return {
+        blocked: [],
+        created: [],
+        overwritten: [],
+        removed: [],
+        skipped: [],
+        updated: [],
+    };
+}
+
+function mergeEnsureInstructionResults(result: TEnsureInstructionFilesResult, next: TEnsureInstructionFilesResult) {
+    result.created.push(...next.created);
+    result.overwritten.push(...next.overwritten);
+    result.removed.push(...next.removed);
+    result.updated.push(...next.updated);
+    result.skipped.push(...next.skipped);
+    result.blocked.push(...next.blocked);
+}
+
+function getManagedInstructionProjectPaths(instructionDefinitions: TAgentInstructionDefinition[]) {
+    const projectPaths: string[] = [];
+
+    for (const instructionDefinition of instructionDefinitions) {
+        projectPaths.push(instructionDefinition.projectPath);
+
+        const claudeProjectPath = getClaudeCompanionProjectPath(instructionDefinition.projectPath);
+        if (claudeProjectPath) projectPaths.push(claudeProjectPath);
+    }
+
+    return projectPaths;
+}
+
+function getClaudeCompanionProjectPath(projectPath: string) {
+    if (path.basename(projectPath).toLowerCase() !== agentInstructionFilename.toLowerCase()) return undefined;
+
+    return path.join(path.dirname(projectPath), claudeInstructionFilename);
+}
+
 function removeInstructionGitignoreEntries({
     rootDir,
     instructionDefinitions,
@@ -254,7 +296,7 @@ function removeInstructionGitignoreEntries({
     if (!pathEntryExists(gitignoreFilepath)) return false;
 
     const managedEntries = new Set(
-        instructionDefinitions.map((instructionDefinition) => normalizeGitignoreEntry(instructionDefinition.projectPath)),
+        getManagedInstructionProjectPaths(instructionDefinitions).map((projectPath) => normalizeGitignoreEntry(projectPath)),
     );
     const lines = fs.readFileSync(gitignoreFilepath, 'utf8').split(/\r?\n/);
     const filteredLines: string[] = [];
@@ -341,12 +383,28 @@ function ensureInstructionFiles(
                     : upsertManagedInstructionSection(existingState.content, instructionContent);
             if (nextContent === existingState.content) {
                 result.skipped.push(relativeProjectPath);
+                ensureClaudeCompanionIfNeeded({
+                    dryRun,
+                    instructionDefinition,
+                    logPrefix,
+                    overwriteBlockedPaths,
+                    result,
+                    rootDir,
+                });
                 continue;
             }
 
             if (!dryRun) fs.writeFileSync(projectFilepath, nextContent);
             result.updated.push(relativeProjectPath);
             logVerbose(`${logPrefix} Updated ${relativeProjectPath}`);
+            ensureClaudeCompanionIfNeeded({
+                dryRun,
+                instructionDefinition,
+                logPrefix,
+                overwriteBlockedPaths,
+                result,
+                rootDir,
+            });
             continue;
         }
 
@@ -357,6 +415,14 @@ function ensureInstructionFiles(
             }
             result.updated.push(relativeProjectPath);
             logVerbose(`${logPrefix} Updated ${relativeProjectPath}`);
+            ensureClaudeCompanionIfNeeded({
+                dryRun,
+                instructionDefinition,
+                logPrefix,
+                overwriteBlockedPaths,
+                result,
+                rootDir,
+            });
             continue;
         }
 
@@ -373,12 +439,28 @@ function ensureInstructionFiles(
             }
             result.overwritten.push(relativeProjectPath);
             logVerbose(`${logPrefix} Replaced ${relativeProjectPath}`);
+            ensureClaudeCompanionIfNeeded({
+                dryRun,
+                instructionDefinition,
+                logPrefix,
+                overwriteBlockedPaths,
+                result,
+                rootDir,
+            });
             continue;
         }
 
         if (!dryRun) fs.writeFileSync(projectFilepath, instructionContent);
         result.created.push(relativeProjectPath);
         logVerbose(`${logPrefix} Created ${relativeProjectPath}`);
+        ensureClaudeCompanionIfNeeded({
+            dryRun,
+            instructionDefinition,
+            logPrefix,
+            overwriteBlockedPaths,
+            result,
+            rootDir,
+        });
     }
 
     return result;
@@ -422,6 +504,13 @@ function removeManagedInstructionFiles(
             if (!dryRun) fs.removeSync(projectFilepath);
             result.removed.push(relativeProjectPath);
             logVerbose(`${logPrefix} Removed retired app-root ${relativeProjectPath}`);
+            removeClaudeCompanionIfNeeded({
+                dryRun,
+                instructionDefinition,
+                logPrefix,
+                result,
+                rootDir,
+            });
             continue;
         }
 
@@ -437,6 +526,13 @@ function removeManagedInstructionFiles(
                 if (!dryRun) fs.removeSync(projectFilepath);
                 result.removed.push(relativeProjectPath);
                 logVerbose(`${logPrefix} Removed retired app-root ${relativeProjectPath}`);
+                removeClaudeCompanionIfNeeded({
+                    dryRun,
+                    instructionDefinition,
+                    logPrefix,
+                    result,
+                    rootDir,
+                });
                 continue;
             }
 
@@ -452,6 +548,179 @@ function removeManagedInstructionFiles(
     return result;
 }
 
+function ensureClaudeCompanionIfNeeded({
+    dryRun,
+    instructionDefinition,
+    logPrefix,
+    overwriteBlockedPaths,
+    result,
+    rootDir,
+}: {
+    dryRun: boolean;
+    instructionDefinition: TAgentInstructionDefinition;
+    logPrefix: string;
+    overwriteBlockedPaths: Set<string>;
+    result: TEnsureInstructionFilesResult;
+    rootDir: string;
+}) {
+    const claudeProjectPath = getClaudeCompanionProjectPath(instructionDefinition.projectPath);
+    if (!claudeProjectPath) return;
+
+    mergeEnsureInstructionResults(
+        result,
+        ensureClaudeInstructionSymlink({
+            claudeProjectPath,
+            dryRun,
+            logPrefix,
+            overwriteBlockedPaths,
+            rootDir,
+        }),
+    );
+}
+
+function ensureClaudeInstructionSymlink({
+    claudeProjectPath,
+    dryRun,
+    logPrefix,
+    overwriteBlockedPaths,
+    rootDir,
+}: {
+    claudeProjectPath: string;
+    dryRun: boolean;
+    logPrefix: string;
+    overwriteBlockedPaths: Set<string>;
+    rootDir: string;
+}): TEnsureInstructionFilesResult {
+    const result = createEmptyInstructionResult();
+    const claudeFilepath = path.join(rootDir, claudeProjectPath);
+    const claudeParentDir = path.dirname(claudeFilepath);
+    const relativeClaudePath = path.relative(rootDir, claudeFilepath) || '.';
+
+    if (!fs.existsSync(claudeParentDir)) {
+        result.skipped.push(relativeClaudePath);
+        return result;
+    }
+
+    const existingState = inspectExistingClaudePath(claudeFilepath);
+
+    if (existingState.kind === 'correct') {
+        result.skipped.push(relativeClaudePath);
+        return result;
+    }
+
+    if (existingState.kind === 'missing') {
+        if (!dryRun) fs.symlinkSync(agentInstructionFilename, claudeFilepath);
+        result.created.push(relativeClaudePath);
+        logVerbose(`${logPrefix} Created ${relativeClaudePath}`);
+        return result;
+    }
+
+    if (existingState.kind === 'managed-different') {
+        if (!dryRun) {
+            fs.removeSync(claudeFilepath);
+            fs.symlinkSync(agentInstructionFilename, claudeFilepath);
+        }
+        result.updated.push(relativeClaudePath);
+        logVerbose(`${logPrefix} Updated ${relativeClaudePath}`);
+        return result;
+    }
+
+    const normalizedClaudeFilepath = normalizeAbsolutePath(claudeFilepath);
+    if (!overwriteBlockedPaths.has(normalizedClaudeFilepath)) {
+        result.blocked.push(relativeClaudePath);
+        return result;
+    }
+
+    if (!dryRun) {
+        fs.removeSync(claudeFilepath);
+        fs.symlinkSync(agentInstructionFilename, claudeFilepath);
+    }
+    result.overwritten.push(relativeClaudePath);
+    logVerbose(`${logPrefix} Replaced ${relativeClaudePath}`);
+
+    return result;
+}
+
+function removeClaudeCompanionIfNeeded({
+    dryRun,
+    instructionDefinition,
+    logPrefix,
+    result,
+    rootDir,
+}: {
+    dryRun: boolean;
+    instructionDefinition: TAgentInstructionDefinition;
+    logPrefix: string;
+    result: TEnsureInstructionFilesResult;
+    rootDir: string;
+}) {
+    const claudeProjectPath = getClaudeCompanionProjectPath(instructionDefinition.projectPath);
+    if (!claudeProjectPath) return;
+
+    mergeEnsureInstructionResults(
+        result,
+        removeClaudeInstructionSymlink({
+            claudeProjectPath,
+            dryRun,
+            logPrefix,
+            rootDir,
+        }),
+    );
+}
+
+function removeClaudeInstructionSymlink({
+    claudeProjectPath,
+    dryRun,
+    logPrefix,
+    rootDir,
+}: {
+    claudeProjectPath: string;
+    dryRun: boolean;
+    logPrefix: string;
+    rootDir: string;
+}): TEnsureInstructionFilesResult {
+    const result = createEmptyInstructionResult();
+    const claudeFilepath = path.join(rootDir, claudeProjectPath);
+    const relativeClaudePath = path.relative(rootDir, claudeFilepath) || '.';
+
+    if (!pathEntryExists(claudeFilepath)) return result;
+
+    const existingState = inspectExistingClaudePath(claudeFilepath);
+    if (existingState.kind === 'correct' || existingState.kind === 'managed-different') {
+        if (!dryRun) fs.removeSync(claudeFilepath);
+        result.removed.push(relativeClaudePath);
+        logVerbose(`${logPrefix} Removed retired app-root ${relativeClaudePath}`);
+        return result;
+    }
+
+    if (existingState.kind === 'blocked') result.skipped.push(relativeClaudePath);
+
+    return result;
+}
+
+function inspectExistingClaudePath(claudeFilepath: string) {
+    if (!pathEntryExists(claudeFilepath)) return { kind: 'missing' as const };
+
+    const stats = fs.lstatSync(claudeFilepath);
+    const claudeParentDir = path.dirname(claudeFilepath);
+    const agentFilepath = path.join(claudeParentDir, agentInstructionFilename);
+
+    if (stats.isSymbolicLink()) {
+        const rawTarget = fs.readlinkSync(claudeFilepath);
+        const resolvedTarget = path.resolve(claudeParentDir, rawTarget);
+        if (normalizeAbsolutePath(resolvedTarget) !== normalizeAbsolutePath(agentFilepath)) return { kind: 'blocked' as const };
+
+        return rawTarget === agentInstructionFilename ? { kind: 'correct' as const } : { kind: 'managed-different' as const };
+    }
+
+    if (!stats.isFile()) return { kind: 'blocked' as const };
+
+    const content = fs.readFileSync(claudeFilepath, 'utf8');
+    if (content.trim() === claudeInstructionPointerContent) return { kind: 'managed-different' as const };
+
+    return { kind: 'blocked' as const };
+}
+
 function inspectExistingPath({
     managedSourceRoot,
     projectFilepath,

package/docs/diagnostics.md

@@ -112,7 +112,7 @@ Default compact command output follows this shape:
 
 `proteum runtime status` emits the current app manifest summary, tracked dev sessions, selected live session, MCP URL, health status, configured router/HMR port inspection, and a suggested next command. Use it before starting another dev server, and use its Start Dev command instead of probing page bodies when the default port is occupied. If it reports that the same app already responds on the configured port without a live tracked session, use or repair that runtime instead of starting a second server.
 
-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, `.env`, `.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.
+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.
 

package/package.json

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

package/tests/agents-utils.test.cjs

@@ -15,6 +15,23 @@ const writeFile = (filepath, content) => {
     fs.writeFileSync(filepath, content);
 };
 
+const assertClaudeSymlink = (root, relativeDir = '') => {
+    const linkPath = path.join(root, relativeDir, 'CLAUDE.md');
+    const stats = fs.lstatSync(linkPath);
+
+    assert.equal(stats.isSymbolicLink(), true, `${linkPath} should be a symlink`);
+    assert.equal(fs.readlinkSync(linkPath), 'AGENTS.md');
+};
+
+const pathEntryExists = (filepath) => {
+    try {
+        fs.lstatSync(filepath);
+        return true;
+    } catch {
+        return false;
+    }
+};
+
 const makeTempRoot = () => fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-agents-'));
 
 const createCoreFixture = () => {
@@ -53,6 +70,7 @@ const createAppFixture = () => {
             'node_modules',
             '# Proteum-managed instruction files',
             '/AGENTS.md',
+            '/CLAUDE.md',
             '/CODING_STYLE.md',
             '/DOCUMENTATION.md',
             '# End Proteum-managed instruction files',
@@ -137,9 +155,17 @@ test('standalone configure creates tracked instruction files with routing contra
     assert.equal(fs.existsSync(path.join(appRoot, 'tests', 'e2e', 'REAL_WORLD_JOURNEY_TESTS.md')), true);
     assert.match(fs.readFileSync(path.join(appRoot, 'tests', 'e2e', 'REAL_WORLD_JOURNEY_TESTS.md'), 'utf8'), /Journey rule/);
     assert.doesNotMatch(fs.readFileSync(path.join(appRoot, 'tests', 'e2e', 'REAL_WORLD_JOURNEY_TESTS.md'), 'utf8'), /## Source: CODING_STYLE\.md/);
+    assertClaudeSymlink(appRoot);
+    assertClaudeSymlink(appRoot, 'client');
+    assertClaudeSymlink(appRoot, 'client/pages');
+    assertClaudeSymlink(appRoot, 'server/routes');
+    assertClaudeSymlink(appRoot, 'server/services');
+    assertClaudeSymlink(appRoot, 'tests');
+    assertClaudeSymlink(appRoot, 'tests/e2e');
     assert.doesNotMatch(agentsContent, /Before reading or applying instructions from this file/);
     assert.doesNotMatch(gitignoreContent, /Proteum-managed instruction files/);
     assert.doesNotMatch(gitignoreContent, /^\/AGENTS\.md$/m);
+    assert.doesNotMatch(gitignoreContent, /^\/CLAUDE\.md$/m);
     assert.doesNotMatch(gitignoreContent, /^\/DOCUMENTATION\.md$/m);
 });
 
@@ -255,13 +281,20 @@ test('monorepo configure writes root and app instruction files', () => {
     assert.match(fs.readFileSync(path.join(monorepoRoot, 'tests', 'e2e', 'AGENTS.md'), 'utf8'), /## Source: tests\/e2e\/AGENTS\.md/);
     assert.match(fs.readFileSync(path.join(monorepoRoot, 'tests', 'e2e', 'REAL_WORLD_JOURNEY_TESTS.md'), 'utf8'), /## Source: tests\/e2e\/REAL_WORLD_JOURNEY_TESTS\.md/);
     assert.doesNotMatch(fs.readFileSync(path.join(monorepoRoot, 'tests', 'e2e', 'REAL_WORLD_JOURNEY_TESTS.md'), 'utf8'), /## Source: CODING_STYLE\.md/);
+    assertClaudeSymlink(monorepoRoot);
+    assertClaudeSymlink(monorepoRoot, 'tests');
+    assertClaudeSymlink(monorepoRoot, 'tests/e2e');
     assert.equal(fs.existsSync(path.join(appRoot, 'tests', 'AGENTS.md')), false);
     assert.equal(fs.existsSync(path.join(appRoot, 'tests', 'e2e', 'AGENTS.md')), false);
+    assert.equal(pathEntryExists(path.join(appRoot, 'tests', 'CLAUDE.md')), false);
+    assert.equal(pathEntryExists(path.join(appRoot, 'tests', 'e2e', 'CLAUDE.md')), false);
     const appAgentsContent = fs.readFileSync(path.join(appRoot, 'AGENTS.md'), 'utf8');
     assert.match(appAgentsContent, /## Agent Routing Contract/);
     assert.doesNotMatch(appAgentsContent, /## Known Proteum Apps/);
     assert.doesNotMatch(appAgentsContent, /Do not start `npx proteum dev` from this root/);
     assert.match(fs.readFileSync(path.join(appRoot, 'client', 'AGENTS.md'), 'utf8'), /## Source: client\/AGENTS\.md/);
+    assertClaudeSymlink(appRoot);
+    assertClaudeSymlink(appRoot, 'client');
     assert.equal(fs.existsSync(path.join(appRoot, 'CODING_STYLE.md')), false);
     assert.equal(fs.existsSync(path.join(appRoot, 'DOCUMENTATION.md')), false);
     assert.equal(fs.existsSync(path.join(appRoot, 'diagnostics.md')), false);
@@ -331,6 +364,45 @@ test('configure migrates legacy managed symlinks to tracked files', () => {
     assert.equal(result.updated.some((entry) => entry.endsWith('/AGENTS.md')), true);
     assert.equal(stats.isSymbolicLink(), false);
     assert.match(content, /# Proteum Instructions/);
+    assertClaudeSymlink(appRoot);
+});
+
+test('configure migrates one-line Claude pointer files to symlinks', () => {
+    const coreRoot = createCoreFixture();
+    const appRoot = createAppFixture();
+    const linkPath = path.join(appRoot, 'CLAUDE.md');
+
+    writeFile(linkPath, '@AGENTS.md\n');
+
+    const result = configureProjectAgentInstructions({ appRoot, coreRoot });
+
+    assert.equal(result.updated.some((entry) => entry.endsWith('/CLAUDE.md')), true);
+    assertClaudeSymlink(appRoot);
+});
+
+test('configure reports blocked Claude companion paths unless overwrite is allowed', () => {
+    const coreRoot = createCoreFixture();
+    const appRoot = createAppFixture();
+    const blockedPath = path.join(appRoot, 'CLAUDE.md');
+
+    writeFile(blockedPath, '# Local Claude Notes\n\n- Keep this local rule.\n');
+
+    const preview = configureProjectAgentInstructions({ appRoot, coreRoot, dryRun: true });
+    assert.equal(preview.blocked.some((entry) => entry.endsWith('/CLAUDE.md')), true);
+
+    const blockedResult = configureProjectAgentInstructions({ appRoot, coreRoot });
+    assert.equal(blockedResult.blocked.some((entry) => entry.endsWith('/CLAUDE.md')), true);
+    assert.equal(fs.lstatSync(blockedPath).isFile(), true);
+    assert.match(fs.readFileSync(blockedPath, 'utf8'), /Keep this local rule/);
+
+    const result = configureProjectAgentInstructions({
+        appRoot,
+        coreRoot,
+        overwriteBlockedPaths: [blockedPath],
+    });
+
+    assert.equal(result.overwritten.some((entry) => entry.endsWith('/CLAUDE.md')), true);
+    assertClaudeSymlink(appRoot);
 });
 
 test('configure reports blocked paths unless overwrite is allowed', () => {

package/tests/worktree-bootstrap.test.cjs

@@ -153,6 +153,81 @@ test('worktree bootstrap requires a source env only when .env is missing', async
     assert.equal(result.status.blocking, false);
 });
 
+test('worktree bootstrap copies workspace root env for monorepo root tooling', async () => {
+    const targetRepoRoot = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-worktree-monorepo-')), '.codex', 'worktrees', 'fixture-repo');
+    const appRoot = path.join(targetRepoRoot, 'apps', 'product');
+    const sourceRepoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-worktree-source-repo-'));
+    const sourceAppRoot = path.join(sourceRepoRoot, 'apps', 'product');
+
+    writeFile(path.join(targetRepoRoot, 'package.json'), '{"workspaces":["apps/*"]}\n');
+    writeFile(path.join(targetRepoRoot, 'package-lock.json'), '{"lockfileVersion":3}\n');
+    writeFile(path.join(targetRepoRoot, 'prisma.config.ts'), 'export default {};\n');
+    fs.mkdirSync(path.join(targetRepoRoot, 'node_modules'), { recursive: true });
+    writeFile(path.join(appRoot, 'package.json'), '{"name":"fixture-product"}\n');
+    writeFile(path.join(appRoot, 'proteum.config.ts'), 'export default {};\n');
+    writeFile(path.join(appRoot, 'AGENTS.md'), '# Agents\n');
+    writeFile(path.join(appRoot, '.proteum', 'manifest.json'), '{"version":10}\n');
+
+    writeFile(path.join(sourceRepoRoot, 'package.json'), '{"workspaces":["apps/*"]}\n');
+    writeFile(path.join(sourceRepoRoot, 'package-lock.json'), '{"lockfileVersion":3}\n');
+    writeFile(path.join(sourceRepoRoot, 'prisma.config.ts'), 'export default {};\n');
+    writeFile(path.join(sourceRepoRoot, '.env'), 'DATABASE_URL=postgres://root\n');
+    writeFile(path.join(sourceAppRoot, '.env'), 'PORT=3021\n');
+
+    const result = await runWorktreeBootstrapInit({
+        appRoot,
+        coreRoot,
+        proteumVersion: 'test',
+        runDependencies: noOpDeps,
+        runRefresh: noOpRefresh,
+        runRuntimeStatus: noOpRuntime,
+        source: sourceAppRoot,
+    });
+
+    assert.equal(fs.readFileSync(path.join(appRoot, '.env'), 'utf8'), 'PORT=3021\n');
+    assert.equal(fs.readFileSync(path.join(targetRepoRoot, '.env'), 'utf8'), 'DATABASE_URL=postgres://root\n');
+    assert.equal(result.marker.env.root.present, true);
+    assert.equal(result.marker.env.root.copied, true);
+    assert.equal(result.status.blocking, false);
+});
+
+test('worktree bootstrap falls back to source app env for missing workspace root env', async () => {
+    const targetRepoRoot = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-worktree-root-env-fallback-')), '.codex', 'worktrees', 'fixture-repo');
+    const appRoot = path.join(targetRepoRoot, 'apps', 'api');
+    const sourceRepoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-worktree-source-repo-fallback-'));
+    const sourceAppRoot = path.join(sourceRepoRoot, 'apps', 'api');
+
+    writeFile(path.join(targetRepoRoot, 'package.json'), '{"workspaces":["apps/*"]}\n');
+    writeFile(path.join(targetRepoRoot, 'package-lock.json'), '{"lockfileVersion":3}\n');
+    writeFile(path.join(targetRepoRoot, 'prisma.config.ts'), 'export default {};\n');
+    fs.mkdirSync(path.join(targetRepoRoot, 'node_modules'), { recursive: true });
+    writeFile(path.join(appRoot, 'package.json'), '{"name":"fixture-api"}\n');
+    writeFile(path.join(appRoot, 'proteum.config.ts'), 'export default {};\n');
+    writeFile(path.join(appRoot, 'AGENTS.md'), '# Agents\n');
+    writeFile(path.join(appRoot, '.proteum', 'manifest.json'), '{"version":10}\n');
+
+    writeFile(path.join(sourceRepoRoot, 'package.json'), '{"workspaces":["apps/*"]}\n');
+    writeFile(path.join(sourceRepoRoot, 'package-lock.json'), '{"lockfileVersion":3}\n');
+    writeFile(path.join(sourceRepoRoot, 'prisma.config.ts'), 'export default {};\n');
+    writeFile(path.join(sourceAppRoot, '.env'), 'DATABASE_URL=postgres://app\nPORT=3022\n');
+
+    const result = await runWorktreeBootstrapInit({
+        appRoot,
+        coreRoot,
+        proteumVersion: 'test',
+        runDependencies: noOpDeps,
+        runRefresh: noOpRefresh,
+        runRuntimeStatus: noOpRuntime,
+        source: sourceAppRoot,
+    });
+
+    assert.equal(fs.readFileSync(path.join(appRoot, '.env'), 'utf8'), 'DATABASE_URL=postgres://app\nPORT=3022\n');
+    assert.equal(fs.readFileSync(path.join(targetRepoRoot, '.env'), 'utf8'), 'DATABASE_URL=postgres://app\nPORT=3022\n');
+    assert.equal(result.marker.env.root.present, true);
+    assert.equal(result.marker.env.root.source, path.join(sourceAppRoot, '.env'));
+    assert.equal(result.status.blocking, false);
+});
+
 test('worktree bootstrap detects missing env manifest node_modules and version changes', async () => {
     const appRoot = createCodexAppRoot();
     writeBootstrapFixture(appRoot);