proteum 2.2.0 → 2.2.2-1

package/AGENTS.md

@@ -32,7 +32,7 @@ cd <worktree path>
 npx prisma migrate dev --config ./prisma.config.ts --name <migration name>
 ```
 - After implementing a framework feature or change, do not stop at code edits. Boot both reference apps, exercise the affected flow with Playwright or the smallest real Proteum surface, run the relevant `proteum` diagnostics or perf commands, and confirm there is no meaningful regression in runtime behavior, performance, load size, SEO output, or coding-style expectations before finishing.
-- When starting a long-lived reference app dev server for framework work, always request elevated permissions and run `npx proteum dev` outside the sandbox. Use an explicit thread-scoped session file such as `var/run/proteum/dev/framework-<app>-<task>.json`, inspect tracked sessions plus current listeners first, for example with `npx proteum dev list --json` and `lsof -nP -iTCP -sTCP:LISTEN`, then choose a port that is not currently used before starting `npx proteum dev --session-file <path> --port <port>`.
+- When starting a long-lived reference app dev server for framework work, always request elevated permissions and run `npx proteum dev` outside the sandbox. Use an explicit thread-scoped session file such as `var/run/proteum/dev/framework-<app>-<task>.json`, inspect tracked sessions plus current listeners first, for example with `npx proteum dev list --json` and `lsof -nP -iTCP -sTCP:LISTEN`, then choose a port that is not currently used before starting `npx proteum dev --session-file <path> --port <port>`. After the server is ready, print the live server URL as a clickable Markdown link such as `[http://localhost:3100](http://localhost:3100)`.
 - Do not use `--replace-existing` unless you are 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.
 - When a reference app uses local `file:` connected projects for the affected flow, boot every connected producer app as well, each on its own free port and thread-scoped session file, and run every one of those `proteum dev` processes with elevated permissions outside the sandbox before starting or validating the consumer app.
 - Before retrying a boot on the same app, changing ports, or finishing the task, stop every framework-started dev session with `npx proteum dev stop --session-file <path>` or `npx proteum dev stop --all --stale`.
@@ -43,7 +43,7 @@ npx prisma migrate dev --config ./prisma.config.ts --name <migration name>
 
   [optional body]
   ```
-  If the user replies exactly `commit`, use that Conventional Commit message, stage the task-related changed files with `git add` while avoiding unrelated user changes or incidental untracked files, then create the commit by running `git commit`.
+  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.
   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.`
 
@@ -51,12 +51,14 @@ npx prisma migrate dev --config ./prisma.config.ts --name <migration name>
 
 - Validate framework changes against the reference apps:
   - `/Users/gaetan/Desktop/Projets/crosspath/platform`: Standalone app
+  - `/Users/gaetan/Desktop/Projets/crosspath/website`: Standalone app
   - `/Users/gaetan/Desktop/Projets/unique.domains/platform`: Monorepo including the following apps:
     - `/Users/gaetan/Desktop/Projets/unique.domains/platform/apps/product`
     - `/Users/gaetan/Desktop/Projets/unique.domains/platform/apps/website`
 - Inspect how both apps currently use the touched feature, runtime, API, compiler behavior, or generated output before proposing or implementing changes.
 - 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.
-- 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 banner. 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.
+- 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 banner. 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. When the app root is missing `AGENTS.md`, the bare interactive `proteum dev` start offers to launch `proteum configure agents` 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

@@ -6,6 +6,12 @@ It is built for teams that want explicit server contracts, server-first renderin
 
 Migration guide for older apps: [docs/migrate-from-2.1.3.md](docs/migrate-from-2.1.3.md)
 
+## Sponsor
+
+Proteum is sponsored by [Unique Domains](https://unique.domains/?utm_source=github&utm_medium=referral&utm_campaign=repo_proteum&utm_content=top_sponsor).
+
+[![Unique Domains](docs/assets/unique-domains-chip.png)](https://unique.domains/?utm_source=github&utm_medium=referral&utm_campaign=repo_proteum&utm_content=top_sponsor)
+
 ## Why Proteum
 
 Most full-stack frameworks optimize first for human convenience.
@@ -101,6 +107,7 @@ Optional trace env vars:
 - `TRACE_EVENTS_LIMIT`
 - `TRACE_CAPTURE`
 - `TRACE_PERSIST_ON_ERROR`
+- `ENABLE_PROFILER`
 
 Optional `proteum.config.ts` fields:
 
@@ -353,7 +360,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.
+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. When the app root is missing `AGENTS.md`, the interactive `proteum dev` start offers to launch `proteum configure agents` before the dev loop begins.
 
 Useful inspection commands:
 
@@ -397,6 +404,8 @@ proteum create service Conversion/Plans
 
 `proteum configure agents` asks before replacing any existing non-managed instruction file or foreign symlink. If you decline, that path is left untouched.
 
+Bare interactive `proteum dev` reuses that same wizard when the app root is missing `AGENTS.md`; declining the prompt continues the dev start without writing files.
+
 `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. For the full diagnostics and tracing model, see [docs/diagnostics.md](docs/diagnostics.md) and [docs/request-tracing.md](docs/request-tracing.md).
 
 ## Dev Commands
@@ -464,6 +473,7 @@ Default behavior:
 - payloads are summarized, long strings are truncated, and sensitive fields such as cookies, passwords, and tokens are redacted
 - `TRACE_PERSIST_ON_ERROR` can export crashing requests under `var/traces/`
 - `proteum dev` removes auto-persisted crash traces from `var/traces/` when the dev session stops
+- `ENABLE_PROFILER=true` reuses the same instrumentation path to populate `request.profiling` and the router `request.finished` hook with a reduced request/API/SQL snapshot in any environment, without retaining finished requests in the global trace buffer unless dev trace is also enabled
 
 Trace env example:
 
@@ -473,6 +483,7 @@ export TRACE_REQUESTS_LIMIT=200
 export TRACE_EVENTS_LIMIT=800
 export TRACE_CAPTURE=resolve
 export TRACE_PERSIST_ON_ERROR=true
+export ENABLE_PROFILER=true
 ```
 
 Capture modes:
@@ -500,7 +511,7 @@ Proteum answers those questions with explicit artifacts:
 
 - `identity.config.ts` for app identity
 - `proteum.config.ts` for compiler and connected-project setup
-- `PORT`, `ENV_*`, `URL`, `URL_INTERNAL`, app-chosen connected-project config values, and `TRACE_*` env vars for the environment surface
+- `PORT`, `ENV_*`, `URL`, `URL_INTERNAL`, app-chosen connected-project config values, `TRACE_*`, and `ENABLE_PROFILER` env vars for the environment surface
 - `server/index.ts` for the explicit root service graph
 - `.proteum/manifest.json` for machine-readable app structure
 - `proteum explain --json` for structured framework introspection
@@ -516,7 +527,7 @@ Proteum answers those questions with explicit artifacts:
 If you are an LLM or automation agent, start here:
 
 1. Read `identity.config.ts` and `proteum.config.ts`.
-2. Read `PORT`, the relevant `ENV_*`, `URL`, `URL_INTERNAL`, any env values referenced by `proteum.config.ts`, and `TRACE_*` env vars, or run `proteum explain env`.
+2. Read `PORT`, the relevant `ENV_*`, `URL`, `URL_INTERNAL`, any env values referenced by `proteum.config.ts`, plus `TRACE_*` and `ENABLE_PROFILER`, or run `proteum explain env`.
 3. Inspect `server/index.ts` and `server/config/*.ts` for the explicit app bootstrap.
 4. Read `.proteum/manifest.json` or run `proteum explain --json`.
 5. Inspect `server/controllers/**` for request entrypoints.

package/agents/project/AGENTS.md

@@ -17,12 +17,14 @@ Coding style source of truth: root-level `CODING_STYLE.md`.
   - Run `npx proteum refresh`.
   - Read and acknowledge the applicable `AGENTS.md` files.
   - Run `npm i`.
-  - Run the dev server with the task-safe elevated-permissions launch workflow from `Task Lifecycle`, and keep it running so user can see the results by himself.
-- If the user pastes raw errors without asking for a fix, do not implement changes. List likely causes and, for each one, give probability, why, and how to fix it.
+  - Run the dev server with the task-safe elevated-permissions launch workflow from `Task Lifecycle`, keep it running so user can see the results by himself, and print the live server URL as a clickable Markdown link.
+- If the user pastes raw errors without asking for a fix, do not implement changes. List likely causes and, for each one, give probability, why, and how to fix it. After this, everytime you implemented a fix
+    - test, re-run analysis and give a comparizon table of before and after
+    - re-print the complete list of suggested fixes, but strike the ones we already implemented or not necessary anymore
 - If the task is ambiguous, generated, connected, or multi-repo, start with `npx proteum orient <query>` before reading large parts of the codebase.
 - If the user reports an issue, or the agent encounters one during exploration, implementation, verification, or runtime reproduction, load and follow root-level `diagnostics.md`.
 - If the task touches client-side files, especially `client/**` and page files, load and apply root-level `optimizations.md` only after implementation for post-implementation checking and optimization. Skip it at task start and skip it for server-only, test-only, doc-only, and non-client refactor tasks unless the user explicitly asks for optimization work.
-- If the task changes UX, copy, onboarding, pricing, product semantics, or commercial positioning, read the relevant files under `./docs/` first, especially `docs/PERSONAS.md`, `docs/PRODUCT.md`, and `docs/MARKETING.md` when they exist. If a dev server is already running, print the dev server URL.
+- If the task changes UX, copy, onboarding, pricing, product semantics, or commercial positioning, read the relevant files under `./docs/` first, especially `docs/PERSONAS.md`, `docs/PRODUCT.md`, and `docs/MARKETING.md` when they exist. If a dev server is already running, print the live dev server URL as a clickable Markdown link.
 - If the task needs new app or artifact boilerplate, prefer `npx proteum init ...` and `npx proteum create ...` before creating files by hand. Use `--dry-run --json` when an agent needs a machine-readable plan before writing files.
 - If you changed `schema.prisma`, do not start testing or validation yet. Ask the user to run the following command in the affected worktree directory, replacing the placeholders, and wait for the user to reply exactly `continue` before resuming validation or tests:
   ```
@@ -38,7 +40,7 @@ Coding style source of truth: root-level `CODING_STYLE.md`.
 
   [optional body]
   ```
-  Then use that generated message, stage the task-related changed files with `git add` while avoiding unrelated user changes or incidental untracked files, and create the commit by running `git commit`. Do not stop at only suggesting the message.
+  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.
   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.`
 
@@ -51,16 +53,16 @@ Coding style source of truth: root-level `CODING_STYLE.md`.
 ### During Implementation
 
 - After running `npx proteum create ...`, adapt the generated code to the real feature instead of leaving placeholder logic in place.
-- When starting a long-lived dev server for an agent task, always request elevated permissions and run `npx proteum dev` outside the sandbox. Use an explicit task/thread-scoped session file such as `var/run/proteum/dev/agents/<task>.json`, inspect `npx proteum dev list --json` plus current listeners first, for example with `lsof -nP -iTCP -sTCP:LISTEN`, then choose a port that is not currently used before starting `npx proteum dev --session-file <path> --port <port>`.
+- When starting a long-lived dev server for an agent task, always request elevated permissions and run `npx proteum dev` outside the sandbox. Use an explicit task/thread-scoped session file such as `var/run/proteum/dev/agents/<task>.json`, inspect `npx proteum dev list --json` plus current listeners first, for example with `lsof -nP -iTCP -sTCP:LISTEN`, then choose a port that is not currently used before starting `npx proteum dev --session-file <path> --port <port>`. 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.
 - 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.
 - For raw browser automation, use `npx proteum verify browser` when it matches the task, or direct Playwright with a disposable profile when lower-level control is required. Bootstrap protected browser state through `npx proteum session`.
-- 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 banner. 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.
+- 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 banner. 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. When the app root is missing `AGENTS.md`, the bare interactive `proteum dev` start offers to launch `proteum configure agents` 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.
-- Do not default to project-wide typecheck, `npx proteum check`, or Playwright after every change. Run them only when the user asks for them, when the changed surface specifically requires them, or when a real issue discovered during verification justifies escalation.
+- Do not default to project-wide typecheck or `npx proteum check` after every change. After implementing a new feature or changing existing feature behavior, always update the end-to-end coverage for that behavior and run the full Playwright test suite before finishing. For docs-only, wording-only, type-only, test-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.`
@@ -96,6 +98,7 @@ Coding style source of truth: root-level `CODING_STYLE.md`.
 - Root services are public class fields instantiated with `new ServiceClass(this, config, this)`.
 - Typed root-service config lives in `server/config/*.ts` via `Services.config(ServiceClass, { ... })`.
 - Router plugins are instantiated explicitly inside the `Router` config `plugins` object.
+- Router plugins can subscribe to `request` and `request.finished`; `request.profiling` exists before `request` runs and carries the finalized request/API/SQL snapshot by `request.finished`.
 - Root business services live in `server/services/<Feature>/index.ts`.
 - Root-service config lives in `server/config/*.ts` when the service needs config.
 - Business logic lives in classes that extend `Service` and use `this.services`, `this.models`, and `this.app`.
@@ -174,6 +177,7 @@ Verify at the correct layer:
 - Controller changes: exercise the generated client call or generated `/api/...` endpoint.
 - SSR changes: 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, then update the relevant end-to-end coverage and finish by running the full Playwright suite.
 - Generated, connected, or ownership-ambiguous changes: start with `npx proteum orient <query>` and prefer `npx proteum verify owner <query>` before broad global checks.
 - Browser-visible issues: prefer `npx proteum verify browser <path>` or the narrowest targeted Playwright pass only after request-level verification is insufficient.
 - Raw browser execution beyond `npx proteum verify browser`: use direct Playwright with a disposable profile, and keep that step for the final verifier agent unless a narrower surface cannot reproduce the issue.
@@ -218,7 +222,7 @@ Verify at the correct layer:
 - Never run schema-mutating SQL such as `ALTER TABLE`, `CREATE TABLE`, `DROP TABLE`, or `CREATE INDEX` to change database structure.
 - 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 only task-scoped `git add` and `git commit`. 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. Any other write-mode git action requires an explicit user request.
 
 ## Appendix
 
@@ -238,7 +242,7 @@ Proteum reads:
 - `package.json`
 - `identity.config.ts` for app identity via `Application.identity({ ... })`
 - `proteum.config.ts` for compiler setup via `Application.setup({ transpile, connect })`
-- `process.env` via `PORT`, `ENV_*`, `URL`, `URL_INTERNAL`, any app-chosen connected-project values referenced by `proteum.config.ts`, and `TRACE_*`
+- `process.env` via `PORT`, `ENV_*`, `URL`, `URL_INTERNAL`, any app-chosen connected-project values referenced by `proteum.config.ts`, `TRACE_*`, and `ENABLE_PROFILER`
 - `server/config/*.ts`
 - `server/index.ts`
 - `commands/**/*.ts`
@@ -298,6 +302,6 @@ Prefer scaffold commands before hand-writing boilerplate:
 Edit these only when required, and keep changes minimal and explicit:
 
 - `tsconfig*.json`
-- `PORT`, `ENV_*`, `URL`, and `TRACE_*` env setup
+- `PORT`, `ENV_*`, `URL`, `TRACE_*`, and `ENABLE_PROFILER` env setup
 - Prisma-generated files
 - symbolic links

package/agents/project/app-root/AGENTS.md

@@ -12,5 +12,5 @@ Do not put here: reusable Proteum architecture contracts, shared verification ru
   - Run `npx proteum refresh`.
   - Read and acknowledge the applicable `AGENTS.md` files.
   - Run `npm i`.
-  - Run the dev server with the task-safe elevated-permissions launch workflow from the reusable root `AGENTS.md`, and keep it running so user can see the results by himself.
-- If the task changes UX, copy, onboarding, pricing, product semantics, or commercial positioning, read the relevant files under `./docs/` first, especially `docs/PERSONAS.md`, `docs/PRODUCT.md`, and `docs/MARKETING.md` when they exist. If a dev server is already running, print the dev server URL.
+  - Run the dev server with the task-safe elevated-permissions launch workflow from the reusable root `AGENTS.md`, keep it running so user can see the results by himself, and print the live server URL as a clickable Markdown link. If the bare interactive `proteum dev` start offers to launch `proteum configure agents`, finish that wizard before continuing.
+- If the task changes UX, copy, onboarding, pricing, product semantics, or commercial positioning, read the relevant files under `./docs/` first, especially `docs/PERSONAS.md`, `docs/PRODUCT.md`, and `docs/MARKETING.md` when they exist. If a dev server is already running, print the live dev server URL as a clickable Markdown link.

package/agents/project/diagnostics.md

@@ -12,9 +12,9 @@ This file is the canonical source of truth for diagnostics, temporary instrument
 
 ## Runtime Diagnostics
 
-- 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 dev list --json` plus current listeners first, for example with `lsof -nP -iTCP -sTCP:LISTEN`, then choose a port that is not currently used before starting `npx proteum dev --session-file <path> --port <port>`.
+- 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 dev list --json` plus current listeners first, for example with `lsof -nP -iTCP -sTCP:LISTEN`, then choose a port that is not currently used before starting `npx proteum dev --session-file <path> --port <port>`. 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 banner. 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.
+- 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 banner. 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. When the app root is missing `AGENTS.md`, the bare interactive `npx proteum dev` start offers to launch `npx proteum configure agents` before the dev loop begins.
 - For ownership or repo discovery questions, start with `npx proteum orient <query>` instead of jumping straight into source searches.
 - For request-time issues in dev, start with `npx proteum diagnose <path> --port <port>` when you have a concrete failing route, page, controller path, or request target. It combines owner lookup, manifest diagnostics, contract diagnostics, matching trace data, and buffered server logs in one pass.
 - Prefer focused verification before global checks: `npx proteum verify owner <query>`, `npx proteum verify request <path>`, and only then `npx proteum verify browser <path>` or targeted Playwright when the bug is browser-visible.

package/agents/project/root/AGENTS.md

@@ -30,7 +30,7 @@ Coding style source of truth: root-level `CODING_STYLE.md`.
 
   [optional body]
   ```
-  Then use that generated message, stage the task-related changed files with `git add` while avoiding unrelated user changes or incidental untracked files, and create the commit by running `git commit`. Do not stop at only suggesting the message.
+  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.
   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.`
 
@@ -43,16 +43,16 @@ Coding style source of truth: root-level `CODING_STYLE.md`.
 ### During Implementation
 
 - After running `npx proteum create ...`, adapt the generated code to the real feature instead of leaving placeholder logic in place.
-- When starting a long-lived dev server for an agent task, always request elevated permissions and run `npx proteum dev` outside the sandbox. Use an explicit task/thread-scoped session file such as `var/run/proteum/dev/agents/<task>.json`, inspect `npx proteum dev list --json` plus current listeners first, for example with `lsof -nP -iTCP -sTCP:LISTEN`, then choose a port that is not currently used before starting `npx proteum dev --session-file <path> --port <port>`.
+- When starting a long-lived dev server for an agent task, always request elevated permissions and run `npx proteum dev` outside the sandbox. Use an explicit task/thread-scoped session file such as `var/run/proteum/dev/agents/<task>.json`, inspect `npx proteum dev list --json` plus current listeners first, for example with `lsof -nP -iTCP -sTCP:LISTEN`, then choose a port that is not currently used before starting `npx proteum dev --session-file <path> --port <port>`. 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.
 - 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.
 - For raw browser automation, use `npx proteum verify browser` when it matches the task, or direct Playwright with a disposable profile when lower-level control is required. Bootstrap protected browser state through `npx proteum session`.
-- 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 banner. 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.
+- 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 banner. 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. When the app root is missing `AGENTS.md`, the bare interactive `proteum dev` start offers to launch `proteum configure agents` 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.
-- Do not default to project-wide typecheck, `npx proteum check`, or Playwright after every change. Run them only when the user asks for them, when the changed surface specifically requires them, or when a real issue discovered during verification justifies escalation.
+- Do not default to project-wide typecheck or `npx proteum check` after every change. After implementing a new feature or changing existing feature behavior, always update the end-to-end coverage for that behavior and run the full Playwright test suite before finishing. For docs-only, wording-only, type-only, test-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.`
@@ -88,6 +88,7 @@ Coding style source of truth: root-level `CODING_STYLE.md`.
 - Root services are public class fields instantiated with `new ServiceClass(this, config, this)`.
 - Typed root-service config lives in `server/config/*.ts` via `Services.config(ServiceClass, { ... })`.
 - Router plugins are instantiated explicitly inside the `Router` config `plugins` object.
+- Router plugins can subscribe to `request` and `request.finished`; `request.profiling` exists before `request` runs and carries the finalized request/API/SQL snapshot by `request.finished`.
 - Root business services live in `server/services/<Feature>/index.ts`.
 - Root-service config lives in `server/config/*.ts` when the service needs config.
 - Business logic lives in classes that extend `Service` and use `this.services`, `this.models`, and `this.app`.
@@ -166,6 +167,7 @@ Verify at the correct layer:
 - Controller changes: exercise the generated client call or generated `/api/...` endpoint.
 - SSR changes: 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, then update the relevant end-to-end coverage and finish by running the full Playwright suite.
 - Generated, connected, or ownership-ambiguous changes: start with `npx proteum orient <query>` and prefer `npx proteum verify owner <query>` before broad global checks.
 - Browser-visible issues: prefer `npx proteum verify browser <path>` or the narrowest targeted Playwright pass only after request-level verification is insufficient.
 - Raw browser execution beyond `npx proteum verify browser`: use direct Playwright with a disposable profile, and keep that step for the final verifier agent unless a narrower surface cannot reproduce the issue.
@@ -210,7 +212,7 @@ Verify at the correct layer:
 - Never run schema-mutating SQL such as `ALTER TABLE`, `CREATE TABLE`, `DROP TABLE`, or `CREATE INDEX` to change database structure.
 - 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 only task-scoped `git add` and `git commit`. 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. Any other write-mode git action requires an explicit user request.
 
 ## Appendix
 
@@ -230,7 +232,7 @@ Proteum reads:
 - `package.json`
 - `identity.config.ts` for app identity via `Application.identity({ ... })`
 - `proteum.config.ts` for compiler setup via `Application.setup({ transpile, connect })`
-- `process.env` via `PORT`, `ENV_*`, `URL`, `URL_INTERNAL`, any app-chosen connected-project values referenced by `proteum.config.ts`, and `TRACE_*`
+- `process.env` via `PORT`, `ENV_*`, `URL`, `URL_INTERNAL`, any app-chosen connected-project values referenced by `proteum.config.ts`, `TRACE_*`, and `ENABLE_PROFILER`
 - `server/config/*.ts`
 - `server/index.ts`
 - `commands/**/*.ts`
@@ -290,6 +292,6 @@ Prefer scaffold commands before hand-writing boilerplate:
 Edit these only when required, and keep changes minimal and explicit:
 
 - `tsconfig*.json`
-- `PORT`, `ENV_*`, `URL`, and `TRACE_*` env setup
+- `PORT`, `ENV_*`, `URL`, `TRACE_*`, and `ENABLE_PROFILER` env setup
 - Prisma-generated files
 - symbolic links

package/agents/project/tests/AGENTS.md

@@ -10,9 +10,16 @@ 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.
 - Verify routing, controllers, SSR, and router plugins against a running app when behavior depends on real request handling.
-- After implementing a browser-visible feature or change, prefer a real browser repro against a running app first. Add targeted Playwright coverage only when the user asks for automated coverage, when a stable regression path needs automation, or when manual/browser verification is insufficient.
+- 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. Use a real browser 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.
+- Organize end-to-end tests following the Crosspath platform layout under `tests/e2e/**`.
+- Put runnable scenario entrypoints in `tests/e2e/features/**`, `tests/e2e/specs/<domain>/**`, or `tests/e2e/journeys/**` depending on scope.
+- Put page objects and reusable UI surface wrappers in `tests/e2e/pages/**`.
+- Put reusable multi-step user flows in `tests/e2e/workflows/**`.
+- Put test data builders in `tests/e2e/factories/**` and generic helpers in `tests/e2e/utils/**`.
+- Keep helpers out of spec files when they are reusable, and do not create ad hoc flat test files or duplicate support abstractions when an existing page, workflow, factory, or utility already fits.
 - Locate elements with `data-testid`.
 - Add `data-testid` where needed instead of relying on brittle selectors.
+- Keep end-to-end tests clean, well organized, and non-redundant. Prefer extending or reshaping the most relevant existing scenario over duplicating coverage, and remove or consolidate overlap when the suite becomes repetitive.
 - Reuse root catalog files from `/client/catalogs/**`, `/server/catalogs/**`, or `/common/catalogs/**` instead of duplicating catalog constants in tests.
 - For protected dev flows, prefer `npx proteum session <email> --role <role>` over automating login unless the login flow itself is under test.

package/cli/commands/configure.ts

@@ -155,7 +155,16 @@ const renderConfigureResultSections = (result: TConfigureProjectAgentSymlinksRes
 export const run = async (): Promise<void> => {
     if (cli.args.action !== 'agents') throw new UsageError('Usage: `proteum configure agents`');
 
-    const appRoot = resolveCanonicalPath(cli.paths.appRoot);
+    await runConfigureAgentsWizard();
+};
+
+export const runConfigureAgentsWizard = async ({
+    appRoot = resolveCanonicalPath(cli.paths.appRoot),
+    coreRoot = cli.paths.core.root,
+}: {
+    appRoot?: string;
+    coreRoot?: string;
+} = {}) => {
     assertProteumAppRoot(appRoot);
 
     if (!process.stdin.isTTY || !process.stdout.isTTY) {
@@ -197,7 +206,7 @@ export const run = async (): Promise<void> => {
 
     const preview = configureProjectAgentSymlinks({
         appRoot,
-        coreRoot: cli.paths.core.root,
+        coreRoot,
         dryRun: true,
         monorepoRoot,
     });
@@ -214,7 +223,7 @@ export const run = async (): Promise<void> => {
 
     const result = configureProjectAgentSymlinks({
         appRoot,
-        coreRoot: cli.paths.core.root,
+        coreRoot,
         monorepoRoot,
         overwriteBlockedPaths,
     });

package/cli/commands/dev.ts

@@ -7,6 +7,8 @@ import path from 'path';
 import { spawn, ChildProcess } from 'child_process';
 import fs from 'fs-extra';
 import type { FSWatcher } from 'fs';
+import prompts from 'prompts';
+import { UsageError } from 'clipanion';
 
 // Cor elibs
 import cli from '..';
@@ -20,9 +22,11 @@ import {
 
 // Configs
 import Compiler from '../compiler';
+import { regex } from '../compiler/common';
 import { createDevEventServer } from './devEvents';
 import { renderDevSession, renderServerReadyBanner, renderDevShutdownBanner } from '../presentation/devSession';
 import { clearInteractiveConsole } from '../presentation/welcome';
+import { renderWarning } from '../presentation/ink';
 import {
     createDevSessionRecord,
     inspectDevSessionFile,
@@ -37,6 +41,8 @@ import {
 } from '../runtime/devSessions';
 import { resolveFrameworkInstallInfo } from '../paths';
 import { logVerbose } from '../runtime/verbose';
+import { inspectProjectAgentFiles } from '../utils/agents';
+import { runConfigureAgentsWizard } from './configure';
 
 // Core
 import { app, App } from '../app';
@@ -138,6 +144,45 @@ const createIgnoredWatchMatcher = (outputPaths: string[]) => (watchPath: string)
     return ignoredWatchPathPatterns.test(normalizedWatchPath);
 };
 
+const promptToConfigureAgentsIfMissing = async () => {
+    if (cli.args.json === true) return;
+    if (!process.stdin.isTTY || !process.stdout.isTTY) return;
+
+    const inspection = inspectProjectAgentFiles({ appRoot: app.paths.root });
+    if (!inspection.missing.includes('AGENTS.md')) return;
+
+    console.info(await renderWarning('Proteum could not find the app-root `AGENTS.md` instruction file.'));
+    console.info(
+        [
+            'Missing standard AGENTS files:',
+            ...inspection.missing.map((entry) => `- ${entry}`),
+            '',
+            'Run `proteum configure agents` now before starting the dev server?',
+        ].join('\n'),
+    );
+
+    const response = await prompts(
+        {
+            type: 'confirm',
+            name: 'value',
+            message: 'Run the configure-agents wizard now?',
+            initial: true,
+        },
+        {
+            onCancel: () => {
+                throw new UsageError('Cancelled `proteum dev`.');
+            },
+        },
+    );
+
+    if (response.value !== true) return;
+
+    await runConfigureAgentsWizard({
+        appRoot: app.paths.root,
+        coreRoot: cli.paths.core.root,
+    });
+};
+
 const getDevAppName = (app: App) =>
     app.identity.web?.fullTitle || app.identity.web?.title || app.identity.name || app.packageJson.name || app.paths.root;
 
@@ -481,10 +526,66 @@ function normalizeWatchPath(watchPath: string) {
     return path.resolve(watchPath).replace(/\\/g, '/').replace(/\/$/, '');
 }
 
-const indexedSourceWatchRules: { compilerName: 'server'; root: () => string; relativePathPattern: RegExp }[] = [
-    { compilerName: 'server', root: () => app.paths.root, relativePathPattern: /^commands(?:\/|$)/ },
-    { compilerName: 'server', root: () => cli.paths.core.root, relativePathPattern: /^commands(?:\/|$)/ },
-];
+type TIndexedSourceWatchEvent = 'change' | 'rename';
+type TIndexedSourceWatchCompilerName = 'server' | 'client';
+type TIndexedSourceWatchInvalidateTarget = 'all' | TIndexedSourceWatchCompilerName;
+type TIndexedSourceWatchRule = {
+    compilerName: TIndexedSourceWatchCompilerName;
+    rootPath: string;
+    relativePathPattern: RegExp;
+    eventTypes: TIndexedSourceWatchEvent[];
+    invalidateTarget: TIndexedSourceWatchInvalidateTarget;
+};
+type TNamedWatching = { compiler: { name?: string }; invalidate: () => void };
+type TMultiWatchingLike = TDevWatching & { watchings?: TNamedWatching[] };
+
+const resolveIndexedSourceWatchRules = (): TIndexedSourceWatchRule[] => {
+    const transpileWatchRoots = app.transpileModuleDirectories
+        .map((rootPath) => {
+            try {
+                return fs.realpathSync(rootPath);
+            } catch {
+                return rootPath;
+            }
+        })
+        .map(normalizeWatchPath)
+        .filter((rootPath, index, list) => list.indexOf(rootPath) === index);
+
+    return [
+        {
+            compilerName: 'server',
+            rootPath: app.paths.root,
+            relativePathPattern: /^commands(?:\/|$)/,
+            eventTypes: ['rename'],
+            invalidateTarget: 'all',
+        },
+        {
+            compilerName: 'server',
+            rootPath: cli.paths.core.root,
+            relativePathPattern: /^commands(?:\/|$)/,
+            eventTypes: ['rename'],
+            invalidateTarget: 'all',
+        },
+        ...transpileWatchRoots.map(
+            (rootPath): TIndexedSourceWatchRule => ({
+                compilerName: 'server',
+                rootPath,
+                relativePathPattern: regex.scripts,
+                eventTypes: ['change', 'rename'],
+                invalidateTarget: 'server',
+            }),
+        ),
+    ];
+};
+
+const findCompilerWatching = (
+    watching: TDevWatching,
+    compilerName: TIndexedSourceWatchCompilerName,
+): TNamedWatching | undefined => {
+    const childWatchings = (watching as TMultiWatchingLike).watchings;
+
+    return childWatchings?.find((childWatching) => childWatching.compiler.name === compilerName);
+};
 
 const closeFsWatcher = async (watcher: FSWatcher) => {
     await new Promise<void>((resolve) => {
@@ -501,7 +602,9 @@ const createIndexedSourceWatching = ({
     watching: TDevWatching;
 }): TIndexedSourceWatching => {
     const watchers: FSWatcher[] = [];
-    const pendingChanges = new Map<'server', Set<string>>();
+    const pendingChanges = new Map<TIndexedSourceWatchCompilerName, Set<string>>();
+    const pendingInvalidateTargets = new Set<TIndexedSourceWatchInvalidateTarget>();
+    const recentQueuedChanges = new Map<string, number>();
     let invalidateTimer: NodeJS.Timeout | undefined;
 
     const flushInvalidate = () => {
@@ -512,31 +615,77 @@ const createIndexedSourceWatching = ({
         }
 
         pendingChanges.clear();
-        logVerbose('Indexed source files changed. Invalidating the dev compiler to refresh generated artifacts.');
-        watching.invalidate();
+
+        if (pendingInvalidateTargets.has('all')) {
+            pendingInvalidateTargets.clear();
+            logVerbose('Indexed source files changed. Invalidating the dev compiler to refresh generated artifacts.');
+            watching.invalidate();
+            return;
+        }
+
+        const invalidateTargets = [...pendingInvalidateTargets].filter(
+            (invalidateTarget): invalidateTarget is TIndexedSourceWatchCompilerName => invalidateTarget !== 'all',
+        );
+        pendingInvalidateTargets.clear();
+
+        if (invalidateTargets.length === 0) return;
+
+        logVerbose('Transpiled source files changed. Invalidating the server compiler to refresh mutable package code.');
+        for (const invalidateTarget of invalidateTargets) {
+            const compilerWatching = findCompilerWatching(watching, invalidateTarget);
+
+            if (!compilerWatching) {
+                watching.invalidate();
+                return;
+            }
+
+            compilerWatching.invalidate();
+        }
     };
 
-    const queueInvalidate = (compilerName: 'server', filepath: string) => {
+    const queueInvalidate = ({
+        compilerName,
+        filepath,
+        invalidateTarget,
+    }: {
+        compilerName: TIndexedSourceWatchCompilerName;
+        filepath: string;
+        invalidateTarget: TIndexedSourceWatchInvalidateTarget;
+    }) => {
         const normalizedFilepath = normalizeWatchPath(filepath);
+        const queueKey = `${invalidateTarget}:${compilerName}:${normalizedFilepath}`;
+        const queuedAt = recentQueuedChanges.get(queueKey);
+
+        if (queuedAt !== undefined && Date.now() - queuedAt < 250) return;
+
+        recentQueuedChanges.set(queueKey, Date.now());
         const changedFiles = pendingChanges.get(compilerName) || new Set<string>();
 
         changedFiles.add(normalizedFilepath);
         pendingChanges.set(compilerName, changedFiles);
+        pendingInvalidateTargets.add(invalidateTarget);
 
         if (invalidateTimer) return;
         invalidateTimer = setTimeout(flushInvalidate, 40);
     };
 
-    for (const watchRule of indexedSourceWatchRules) {
-        const rootPath = watchRule.root();
+    for (const watchRule of resolveIndexedSourceWatchRules()) {
+        const rootPath = watchRule.rootPath;
+        if (!fs.existsSync(rootPath)) continue;
 
         watchers.push(
             fs.watch(rootPath, { recursive: true }, (eventType, filename) => {
                 const relativePath = typeof filename === 'string' ? filename.replace(/\\/g, '/').replace(/^\.\//, '') : '';
+                const normalizedEventType: TIndexedSourceWatchEvent = eventType === 'change' ? 'change' : 'rename';
+
                 if (relativePath && !watchRule.relativePathPattern.test(relativePath)) return;
-                if (eventType !== 'rename' && relativePath) return;
+                if (!watchRule.eventTypes.includes(normalizedEventType) && relativePath) return;
 
-                queueInvalidate(watchRule.compilerName, relativePath ? path.join(rootPath, relativePath) : rootPath);
+                queueInvalidate({
+                    compilerName: watchRule.compilerName,
+                    filepath: relativePath ? path.join(rootPath, relativePath) : rootPath,
+                    invalidateTarget: watchRule.invalidateTarget,
+                });
             }),
         );
     }
@@ -731,5 +880,6 @@ export const run = async () => {
         return;
     }
 
+    await promptToConfigureAgentsIfMissing();
     await runDevLoop();
 };